From 5dc88a64920205fe148f6fcb0d2d61ca751b3c6e Mon Sep 17 00:00:00 2001 From: Euripedes Rocha Filho Date: Fri, 14 Aug 2026 16:19:34 +0200 Subject: [PATCH] docs: Fix documentation formatting to improve reading Fixes #336 --- include/mqtt5_client.h | 56 +++++++++++--------- include/mqtt_client.h | 117 +++++++++++++++++++++++++---------------- 2 files changed, 103 insertions(+), 70 deletions(-) diff --git a/include/mqtt5_client.h b/include/mqtt5_client.h index c17e12a..5474d3b 100644 --- a/include/mqtt5_client.h +++ b/include/mqtt5_client.h @@ -208,10 +208,11 @@ typedef struct { * @param client mqtt client handle * @param connect_property connect property * - * @return ESP_ERR_NO_MEM if failed to allocate - * ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL on fail - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_NO_MEM if failed to allocate + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL on fail */ esp_err_t esp_mqtt5_client_set_connect_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_connection_property_config_t *connect_property); @@ -225,9 +226,10 @@ esp_err_t esp_mqtt5_client_set_connect_property(esp_mqtt5_client_handle_t client * @param client mqtt client handle * @param property publish property * - * @return ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL on fail - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL on fail */ esp_err_t esp_mqtt5_client_set_publish_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_publish_property_config_t *property); @@ -241,9 +243,10 @@ esp_err_t esp_mqtt5_client_set_publish_property(esp_mqtt5_client_handle_t client * @param client mqtt client handle * @param property subscribe property * - * @return ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL on fail - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL on fail */ esp_err_t esp_mqtt5_client_set_subscribe_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_subscribe_property_config_t *property); @@ -257,9 +260,10 @@ esp_err_t esp_mqtt5_client_set_subscribe_property(esp_mqtt5_client_handle_t clie * @param client mqtt client handle * @param property unsubscribe property * - * @return ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL on fail - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL on fail */ esp_err_t esp_mqtt5_client_set_unsubscribe_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_unsubscribe_property_config_t *property); @@ -273,10 +277,11 @@ esp_err_t esp_mqtt5_client_set_unsubscribe_property(esp_mqtt5_client_handle_t cl * @param client mqtt client handle * @param property disconnect property * - * @return ESP_ERR_NO_MEM if failed to allocate - * ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL on fail - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_NO_MEM if failed to allocate + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL on fail */ esp_err_t esp_mqtt5_client_set_disconnect_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_disconnect_property_config_t *property); @@ -292,9 +297,10 @@ esp_err_t esp_mqtt5_client_set_disconnect_property(esp_mqtt5_client_handle_t cli * @param item array of user property data (eg. {{"var","val"},{"other","2"}}) * @param item_num number of items in user property data * - * @return ESP_ERR_NO_MEM if failed to allocate - * ESP_FAIL on fail - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_NO_MEM if failed to allocate + * - ESP_FAIL on fail */ esp_err_t esp_mqtt5_client_set_user_property(mqtt5_user_property_handle_t *user_property, esp_mqtt5_user_property_item_t item[], uint8_t item_num); @@ -310,9 +316,10 @@ esp_err_t esp_mqtt5_client_set_user_property(mqtt5_user_property_handle_t *user_ * And malloc number of count item array memory to store the user property data. * Please DO NOT forget the item memory, key and value point in item memory when get user property data successfully. * - * @return ESP_ERR_NO_MEM if failed to allocate - * ESP_FAIL on fail - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_NO_MEM if failed to allocate + * - ESP_FAIL on fail */ esp_err_t esp_mqtt5_client_get_user_property(mqtt5_user_property_handle_t user_property, esp_mqtt5_user_property_item_t *item, uint8_t *item_num); @@ -321,7 +328,8 @@ esp_err_t esp_mqtt5_client_get_user_property(mqtt5_user_property_handle_t user_p * @brief Get MQTT5 client user property list count * * @param user_property user_property handle - * @return user property list count + * @return + * - number of items in the user property list */ uint8_t esp_mqtt5_client_get_user_property_count(mqtt5_user_property_handle_t user_property); diff --git a/include/mqtt_client.h b/include/mqtt_client.h index 2db00cd..53b09e4 100644 --- a/include/mqtt_client.h +++ b/include/mqtt_client.h @@ -411,7 +411,9 @@ typedef struct topic_t { * * @param config *MQTT* configuration structure * - * @return mqtt_client_handle if successfully created, NULL on error + * @return + * - MQTT client handle on success + * - NULL on error */ esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config); @@ -423,7 +425,9 @@ esp_mqtt_client_init(const esp_mqtt_client_config_t *config); * @param client *MQTT* client handle * @param uri * - * @return ESP_FAIL if URI parse error, ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_FAIL if URI parse error */ esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri); @@ -433,9 +437,10 @@ esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, * * @param client *MQTT* client handle * - * @return ESP_OK on success - * ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL on other error + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL on other error */ esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client); @@ -444,9 +449,10 @@ esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client); * * @param client *MQTT* client handle * - * @return ESP_OK on success - * ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL if client is not waiting for reconnection + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL if client is not waiting for reconnection */ esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client); @@ -455,8 +461,9 @@ esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client); * * @param client *MQTT* client handle * - * @return ESP_OK on success - * ESP_ERR_INVALID_ARG on wrong initialization + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization */ esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client); @@ -468,9 +475,10 @@ esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client); * * @param client *MQTT* client handle * - * @return ESP_OK on success - * ESP_ERR_INVALID_ARG on wrong initialization - * ESP_FAIL if client is in invalid state + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_FAIL if client is in invalid state */ esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client); @@ -490,9 +498,10 @@ esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client); * @param topic_type Needs to be char* for single subscription or `esp_mqtt_topic_t` for multiple topics * @param qos_or_size It's either a qos when subscribing to a single topic or the size of the subscription array when subscribing to multiple topics. * - * @return message_id of the subscribe message on success - * -1 on failure - * -2 in case of full outbox. + * @return + * - MQTT Packet Identifier of the SUBSCRIBE packet on success (>= 0) + * - -1 on failure + * - -2 if the outbox is full */ #define esp_mqtt_client_subscribe(client_handle, topic_type, qos_or_size) _Generic((topic_type), \ char *: esp_mqtt_client_subscribe_single, \ @@ -516,9 +525,10 @@ esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client); * @param topic topic filter to subscribe * @param qos Max qos level of the subscription * - * @return message_id of the subscribe message on success - * -1 on failure - * -2 in case of full outbox. + * @return + * - MQTT Packet Identifier of the SUBSCRIBE packet on success (>= 0) + * - -1 on failure + * - -2 if the outbox is full */ int esp_mqtt_client_subscribe_single(esp_mqtt_client_handle_t client, const char *topic, int qos); @@ -537,9 +547,10 @@ int esp_mqtt_client_subscribe_single(esp_mqtt_client_handle_t client, * @param topic_list List of topics to subscribe * @param size size of topic_list * - * @return message_id of the subscribe message on success - * -1 on failure - * -2 in case of full outbox. + * @return + * - MQTT Packet Identifier of the SUBSCRIBE packet on success (>= 0) + * - -1 on failure + * - -2 if the outbox is full */ int esp_mqtt_client_subscribe_multiple(esp_mqtt_client_handle_t client, const esp_mqtt_topic_t *topic_list, int size); @@ -554,8 +565,9 @@ int esp_mqtt_client_subscribe_multiple(esp_mqtt_client_handle_t client, * @param client *MQTT* client handle * @param topic * - * @return message_id of the subscribe message on success - * -1 on failure + * @return + * - MQTT Packet Identifier of the UNSUBSCRIBE packet on success (>= 0) + * - -1 on failure */ int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic); @@ -586,8 +598,10 @@ int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, * @param qos QoS of publish message * @param retain retain flag * - * @return message_id of the publish message (for QoS 0 message_id will always - * be zero) on success. -1 on failure, -2 in case of full outbox. + * @return + * - MQTT Packet Identifier of the PUBLISH packet on success (>= 0; 0 for QoS 0) + * - -1 on failure + * - -2 if the outbox is full */ int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain); @@ -614,7 +628,10 @@ int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic, * @param store if true, all messages are enqueued; otherwise only QoS 1 and * QoS 2 are enqueued * - * @return message_id if queued successfully, -1 on failure, -2 in case of full outbox. + * @return + * - MQTT Packet Identifier of the queued PUBLISH packet on success (>= 0) + * - -1 on failure + * - -2 if the outbox is full */ int esp_mqtt_client_enqueue(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain, @@ -628,8 +645,9 @@ int esp_mqtt_client_enqueue(esp_mqtt_client_handle_t client, const char *topic, * * @param client *MQTT* client handle * - * @return ESP_OK - * ESP_ERR_INVALID_ARG on wrong initialization + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization */ esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client); @@ -644,9 +662,10 @@ esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client); * * @param config *MQTT* configuration structure * - * @return ESP_ERR_NO_MEM if failed to allocate - * ESP_ERR_INVALID_ARG if conflicts on transport configuration. - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if conflicts on transport configuration + * - ESP_ERR_NO_MEM if failed to allocate */ esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, const esp_mqtt_client_config_t *config); @@ -659,9 +678,10 @@ esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, * @param event_handler handler callback * @param event_handler_arg handlers context * - * @return ESP_ERR_NO_MEM if failed to allocate - * ESP_ERR_INVALID_ARG on wrong initialization - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on wrong initialization + * - ESP_ERR_NO_MEM if failed to allocate */ esp_err_t esp_mqtt_client_register_event(esp_mqtt_client_handle_t client, esp_mqtt_event_id_t event, @@ -675,9 +695,10 @@ esp_err_t esp_mqtt_client_register_event(esp_mqtt_client_handle_t client, * @param event event ID * @param event_handler handler to unregister * - * @return ESP_ERR_NO_MEM if failed to allocate - * ESP_ERR_INVALID_ARG on invalid event ID - * ESP_OK on success + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG on invalid event ID + * - ESP_ERR_NO_MEM if failed to allocate */ esp_err_t esp_mqtt_client_unregister_event(esp_mqtt_client_handle_t client, esp_mqtt_event_id_t event, esp_event_handler_t event_handler); @@ -686,8 +707,9 @@ esp_err_t esp_mqtt_client_unregister_event(esp_mqtt_client_handle_t client, esp_ * @brief Get outbox size * * @param client *MQTT* client handle - * @return outbox size - * 0 on wrong initialization + * @return + * - outbox size in bytes + * - 0 on wrong initialization */ int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client); @@ -696,8 +718,9 @@ int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client); * * @param client *MQTT* client handle * @param event *MQTT* event handle structure - * @return ESP_OK on success - * ESP_ERR_TIMEOUT if the event couldn't be queued (ref also CONFIG_MQTT_EVENT_QUEUE_SIZE) + * @return + * - ESP_OK on success + * - ESP_ERR_TIMEOUT if the event couldn't be queued (see also CONFIG_MQTT_EVENT_QUEUE_SIZE) */ esp_err_t esp_mqtt_dispatch_custom_event(esp_mqtt_client_handle_t client, esp_mqtt_event_t *event); @@ -717,8 +740,9 @@ esp_err_t esp_mqtt_dispatch_custom_event(esp_mqtt_client_handle_t client, esp_mq * * @param client *MQTT* client handle * @param transport_scheme Transport handle to search for. - * @return the transport handle - * NULL in case of error + * @return + * - transport handle on success + * - NULL on error * */ esp_transport_handle_t esp_mqtt_client_get_transport(esp_mqtt_client_handle_t client, char *transport_scheme); @@ -730,8 +754,9 @@ esp_transport_handle_t esp_mqtt_client_get_transport(esp_mqtt_client_handle_t cl * reconnection, or disconnected. * * @param client *MQTT* client handle - * @return MQTT client state on success - * MQTT_CLIENT_STATE_INVALID in case of error + * @return + * - MQTT client state on success + * - MQTT_CLIENT_STATE_INVALID on error */ esp_mqtt_client_connection_state_t esp_mqtt_client_get_state(esp_mqtt_client_handle_t client);