[04/90] connection: Document gateway configuration state.

Commit Message

Grant Erickson Dec. 6, 2023, 11:49 p.m. UTC

From: Grant Erickson <[e-mail]>

This adds documentation to the 'gateway_config_state' enumeration.
---
 src/connection.c | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

Patch

diff --git a/src/connection.c b/src/connection.c
index 6c735f761a54..63c22be0cf83 100644
--- a/src/connection.c
+++ b/src/connection.c
@@ -38,12 +38,40 @@ 
 #define GATEWAY_DATA_DBG(description, data) \
 	gateway_data_debug(__func__, description, data)
 
+/**
+ *	@brief
+ *    Indicates the current lifecycle state of the gateway
+ *    configuration.
+ *
+ *  Gateway lifecycle is generally top-down, from user space to
+ *  kernel. That is, Connection Manager manages and adds/sets or
+ *  gateway routes and then uses notifications from the kernel Routing
+ *  Netlink (rtnl) to confirm and "activate" those routes. Likewise,
+ *  Connection Manager removes/clears/deletes gateway routes an then
+ *  uses notifications from the kernel Routing Netlink (rtnl) to
+ *  confirm and "inactivate" those routes.
+ *
+ */
 enum gateway_config_state {
+	/**
+	 *	Indicates whether the gateway, or default router, is inactive.
+	 */
 	CONNMAN_GATEWAY_CONFIG_STATE_INACTIVE = 0,
+
+	/**
+	 *	Indicates whether the gateway, or default router, is added and
+	 *	acknowledged by the kernel through a Routing Netlink (rtnl)
+	 *	notification and, consequently, is active (that is, in use).
+	 */
 	CONNMAN_GATEWAY_CONFIG_STATE_ACTIVE	  = 1
 };
 
 struct gateway_config {
+
+	/**
+	 *	Indicates the current state of the gateway configuration. See
+	 *	#gateway_config_state.
+	 */
 	enum gateway_config_state state;
 	char *gateway;