include: add doxygen documentation

Signed-off-by: Marcin Niestroj <m.niestroj@emb.dev>

Author: mniestroj

include/pouch_gateway/bt/cert.h

@@ -6,4 +6,9 @@
 
 #pragma once
 
+/**
+ * Start certificate exchange for the given Bluetooth connection.
+ *
+ * @param conn The Bluetooth connection.
+ */
 void pouch_gateway_cert_exchange_start(struct bt_conn *conn);

include/pouch_gateway/bt/connect.h

@@ -10,6 +10,31 @@
 
 #include <pouch_gateway/types.h>
 
+/**
+ * Get the node info for the given Bluetooth connection.
+ *
+ * @param conn The Bluetooth connection.
+ * @return Pointer to the node info structure.
+ */
 struct pouch_gateway_node_info *pouch_gateway_get_node_info(const struct bt_conn *conn);
 
+/**
+ * Start Bluetooth operations for the given connection.
+ *
+ * @param conn The Bluetooth connection.
+ */
+void pouch_gateway_bt_start(struct bt_conn *conn);
+
+/**
+ * Stop Bluetooth operations for the given connection.
+ *
+ * @param conn The Bluetooth connection.
+ */
+void pouch_gateway_bt_stop(struct bt_conn *conn);
+
+/**
+ * Finish Bluetooth operations for the given connection.
+ *
+ * @param conn The Bluetooth connection.
+ */
 void pouch_gateway_bt_finished(struct bt_conn *conn);

include/pouch_gateway/bt/downlink.h

@@ -6,5 +6,17 @@
 
 #pragma once
 
+/**
+ * Start downlink for the given Bluetooth connection.
+ *
+ * @param conn The Bluetooth connection.
+ * @return Pointer to the downlink context.
+ */
 struct pouch_gateway_downlink_context *pouch_gateway_downlink_start(struct bt_conn *conn);
+
+/**
+ * Clean up downlink resources for the given Bluetooth connection.
+ *
+ * @param conn The Bluetooth connection.
+ */
 void pouch_gateway_downlink_cleanup(struct bt_conn *conn);

include/pouch_gateway/bt/scan.h

@@ -6,4 +6,7 @@
 
 #pragma once
 
+/**
+ * Start Bluetooth scanning for devices.
+ */
 void pouch_gateway_scan_start(void);

include/pouch_gateway/bt/uplink.h

@@ -6,5 +6,16 @@
 
 #pragma once
 
+/**
+ * Start uplink for the given Bluetooth connection.
+ *
+ * @param conn The Bluetooth connection.
+ */
 void pouch_gateway_uplink_start(struct bt_conn *conn);
+
+/**
+ * Clean up uplink resources for the given Bluetooth connection.
+ *
+ * @param conn The Bluetooth connection.
+ */
 void pouch_gateway_uplink_cleanup(struct bt_conn *conn);

include/pouch_gateway/cert.h

@@ -13,18 +13,85 @@ struct pouch_gateway_server_cert_context;
 #include <stdbool.h>
 #include <stddef.h>
 
+/**
+ * Start device certificate handling.
+ *
+ * @return Pointer to the device certificate context.
+ */
 struct pouch_gateway_device_cert_context *pouch_gateway_device_cert_start(void);
+
+/**
+ * Push data to the device certificate context.
+ *
+ * @param context The device certificate context.
+ * @param data The data to push.
+ * @param len The length of the data.
+ * @return 0 on success, negative on error.
+ */
 int pouch_gateway_device_cert_push(struct pouch_gateway_device_cert_context *context, const void *data, size_t len);
+
+/**
+ * Abort device certificate handling.
+ *
+ * @param context The device certificate context.
+ */
 void pouch_gateway_device_cert_abort(struct pouch_gateway_device_cert_context *context);
+
+/**
+ * Finish device certificate handling.
+ *
+ * @param context The device certificate context.
+ * @return 0 on success, negative on error.
+ */
 int pouch_gateway_device_cert_finish(struct pouch_gateway_device_cert_context *context);
 
+/**
+ * Start server certificate handling.
+ *
+ * @return Pointer to the server certificate context.
+ */
 struct pouch_gateway_server_cert_context *pouch_gateway_server_cert_start(void);
+
+/**
+ * Abort server certificate handling.
+ *
+ * @param context The server certificate context.
+ */
 void pouch_gateway_server_cert_abort(struct pouch_gateway_server_cert_context *context);
+
+/**
+ * Check if the server certificate is the newest.
+ *
+ * @param context The server certificate context.
+ * @return True if newest, false otherwise.
+ */
 bool pouch_gateway_server_cert_is_newest(const struct pouch_gateway_server_cert_context *context);
+
+/**
+ * Check if the server certificate is complete.
+ *
+ * @param context The server certificate context.
+ * @return True if complete, false otherwise.
+ */
 bool pouch_gateway_server_cert_is_complete(const struct pouch_gateway_server_cert_context *context);
+
+/**
+ * Get data from the server certificate context.
+ *
+ * @param context The server certificate context.
+ * @param dst Destination buffer.
+ * @param dst_len Length of the destination buffer.
+ * @param is_last True if this is the last chunk.
+ * @return 0 on success, negative on error.
+ */
 int pouch_gateway_server_cert_get_data(struct pouch_gateway_server_cert_context *context,
                          void *dst,
                          size_t *dst_len,
                          bool *is_last);
 
+/**
+ * Callback when connected to Golioth client for certificate module.
+ *
+ * @param client The Golioth client.
+ */
 void pouch_gateway_cert_module_on_connected(struct golioth_client *client);

include/pouch_gateway/downlink.h

@@ -11,14 +11,73 @@
 struct pouch_gateway_downlink_context;
 typedef void (*pouch_gateway_downlink_data_available_cb)(void *);
 
+/**
+ * Initialize the downlink module with the Golioth client.
+ *
+ * @param client The Golioth client.
+ */
 void pouch_gateway_downlink_module_init(struct golioth_client *client);
+
+/**
+ * Initialize a downlink context.
+ *
+ * @param data_available_cb Callback for when data is available.
+ * @param arg Argument for the callback.
+ * @return Pointer to the downlink context.
+ */
 struct pouch_gateway_downlink_context *pouch_gateway_downlink_init(pouch_gateway_downlink_data_available_cb data_available_cb, void *arg);
+
+/**
+ * Finish the downlink context.
+ *
+ * @param downlink The downlink context.
+ */
 void pouch_gateway_downlink_finish(struct pouch_gateway_downlink_context *downlink);
+
+/**
+ * Abort the downlink context.
+ *
+ * @param downlink The downlink context.
+ */
 void pouch_gateway_downlink_abort(struct pouch_gateway_downlink_context *downlink);
+
+/**
+ * Get data from the downlink context.
+ *
+ * @param downlink The downlink context.
+ * @param dst Destination buffer.
+ * @param dst_len Length of the destination buffer.
+ * @param is_last true if this is the last chunk.
+ * @return 0 on success, negative on error.
+ */
 int pouch_gateway_downlink_get_data(struct pouch_gateway_downlink_context *downlink, void *dst, size_t *dst_len, bool *is_last);
+
+/**
+ * Check if the downlink is complete.
+ *
+ * @param downlink The downlink context.
+ * @return true if complete, false otherwise.
+ */
 bool pouch_gateway_downlink_is_complete(const struct pouch_gateway_downlink_context *downlink);
 
+/**
+ * Block callback for downlink data.
+ *
+ * @param data The data received.
+ * @param len The length of the data.
+ * @param is_last True if this is the last block.
+ * @param arg User argument.
+ * @return Golioth status.
+ */
 enum golioth_status pouch_gateway_downlink_block_cb(const uint8_t *data, size_t len, bool is_last, void *arg);
+
+/**
+ * End callback for downlink.
+ *
+ * @param status Golioth status.
+ * @param coap_rsp_code CoAP response code.
+ * @param arg User argument.
+ */
 void pouch_gateway_downlink_end_cb(enum golioth_status status,
                                    const struct golioth_coap_rsp_code *coap_rsp_code,
                                    void *arg);

include/pouch_gateway/uplink.h

@@ -18,12 +18,38 @@ struct pouch_block;
 
 struct pouch_gateway_uplink;
 
+/**
+ * Write data to the uplink.
+ *
+ * @param uplink The uplink context.
+ * @param payload The payload to write.
+ * @param len The length of the payload.
+ * @param is_last true if this is the last chunk.
+ * @return 0 on success, negative on error.
+ */
 int pouch_gateway_uplink_write(struct pouch_gateway_uplink *uplink,
                        const uint8_t *payload,
                        size_t len,
                        bool is_last);
 
+/**
+ * Open an uplink for the given downlink context.
+ *
+ * @param downlink The downlink context.
+ * @return Pointer to the uplink context.
+ */
 struct pouch_gateway_uplink *pouch_gateway_uplink_open(struct pouch_gateway_downlink_context *downlink);
+
+/**
+ * Close the uplink.
+ *
+ * @param uplink The uplink context.
+ */
 void pouch_gateway_uplink_close(struct pouch_gateway_uplink *uplink);
 
+/**
+ * Initialize the uplink module with the Golioth client.
+ *
+ * @param c The Golioth client.
+ */
 void pouch_gateway_uplink_init(struct golioth_client *c);