api: document gr_dhcp.h

Add comments for DHCP client state machine states, status structure and
API endpoints. Replace informal // STREAM() comment with STREAM_RESP()
macro for compile-time type checking.

Signed-off-by: Robin Jarry <[email protected]>

Author: rjarry

modules/dhcp/api/gr_dhcp.h

@@ -9,51 +9,52 @@
 
 #include <stdint.h>
 
+// DHCP client state machine states (RFC 2131).
 typedef enum dhcp_state : uint8_t {
-	DHCP_STATE_INIT = 0,
-	DHCP_STATE_SELECTING,
-	DHCP_STATE_REQUESTING,
-	DHCP_STATE_BOUND,
-	DHCP_STATE_RENEWING,
-	DHCP_STATE_REBINDING,
+	DHCP_STATE_INIT = 0, // Initial state, no configuration.
+	DHCP_STATE_SELECTING, // Waiting for DHCPOFFER messages.
+	DHCP_STATE_REQUESTING, // Waiting for DHCPACK message.
+	DHCP_STATE_BOUND, // Lease acquired and valid.
+	DHCP_STATE_RENEWING, // Renewing lease with original server (T1 expired).
+	DHCP_STATE_REBINDING, // Rebinding with any server (T2 expired).
 } dhcp_state_t;
 
+// DHCP client status information for an interface.
 struct gr_dhcp_status {
-	uint16_t iface_id;
-	dhcp_state_t state;
-	ip4_addr_t server_ip;
-	ip4_addr_t assigned_ip;
-	uint32_t lease_time;
-	uint32_t renewal_time; // T1
-	uint32_t rebind_time; // T2
+	uint16_t iface_id; // Interface ID running DHCP client.
+	dhcp_state_t state; // Current DHCP state.
+	ip4_addr_t server_ip; // DHCP server IPv4 address.
+	ip4_addr_t assigned_ip; // Assigned IPv4 address.
+	uint32_t lease_time; // Lease duration in seconds.
+	uint32_t renewal_time; // Renewal time (T1) in seconds.
+	uint32_t rebind_time; // Rebinding time (T2) in seconds.
 };
 
 #define GR_DHCP_MODULE 0xd4c9
 
-// list ////////////////////////////////////////////////////////////////////////
-
+// List all active DHCP clients and their status.
 #define GR_DHCP_LIST REQUEST_TYPE(GR_DHCP_MODULE, 0x01)
 
 // struct gr_dhcp_list_req { };
 
 STREAM_RESP(struct gr_dhcp_status);
 
-// start ///////////////////////////////////////////////////////////////////////
-
+// Start DHCP client on an interface.
+// Initiates DHCP discovery to obtain IPv4 address configuration.
 #define GR_DHCP_START REQUEST_TYPE(GR_DHCP_MODULE, 0x02)
 
 struct gr_dhcp_start_req {
-	uint16_t iface_id;
+	uint16_t iface_id; // Interface ID to start DHCP client on.
 };
 
 // struct gr_dhcp_start_resp { };
 
-// stop ////////////////////////////////////////////////////////////////////////
-
+// Stop DHCP client on an interface.
+// Releases the current lease and removes assigned address.
 #define GR_DHCP_STOP REQUEST_TYPE(GR_DHCP_MODULE, 0x03)
 
 struct gr_dhcp_stop_req {
-	uint16_t iface_id;
+	uint16_t iface_id; // Interface ID to stop DHCP client on.
 };
 
 // struct gr_dhcp_stop_resp { };