[2/4] connection: Document 'check_default_gateway'.

Commit Message

Grant Erickson Nov. 29, 2023, 7:39 a.m. UTC

This adds documentation to the 'check_default_gateway' function.
---
 src/connection.c | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

Patch

diff --git a/src/connection.c b/src/connection.c
index 747b744a295e..8f6a08e12cf3 100644
--- a/src/connection.c
+++ b/src/connection.c
@@ -1051,6 +1051,26 @@  static bool choose_default_gateway(struct gateway_data *data,
 	return downgraded;
 }
 
+/**
+ *  @brief
+ *    Check whether the specified gateway should yield or become the
+ *    default.
+ *
+ *  This compares the specified, ostenisbly new, gateway data against
+ *  all, known existing gateway data in the service-to-gateway hash
+ *  and determines whether or not the default should be ceded from an
+ *  existing gateway and given to the new, incoming gateway or vice
+ *  versa.
+ *
+ *  @param[in,out]  activated  A pointer to the mutable gateway data
+ *                             associated with a newly-activated
+ *                             gateway route which is to be checked
+ *                             against existing gateway data.
+ *
+ *  @sa choose_default_gateway
+ *  @sa connection_newgateway
+ *
+ */
 static void check_default_gateway(struct gateway_data *activated)
 {
 	GHashTableIter iter;