Fix doxygen warnings in MQTT Library documentation

libraries/standard/mqtt/include/mqtt.h

@@ -19,6 +19,10 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * @file mqtt.h
+ * @brief User-facing functions of the MQTT 3.1.1 library.
+ */
 #ifndef MQTT_H
 #define MQTT_H
 
@@ -35,14 +39,10 @@
  */
 #define MQTT_PACKET_ID_INVALID    ( ( uint16_t ) 0U )
 
+/* Structures defined in this file. */
 struct MQTTPubAckInfo;
-typedef struct MQTTPubAckInfo         MQTTPubAckInfo_t;
-
 struct MQTTContext;
-typedef struct MQTTContext            MQTTContext_t;
-
 struct MQTTDeserializedInfo;
-typedef struct MQTTDeserializedInfo   MQTTDeserializedInfo_t;
 
 /**
  * @brief Application provided callback to retrieve the current time in
@@ -64,9 +64,9 @@ typedef uint32_t (* MQTTGetCurrentTimeFunc_t )( void );
  * @param[in] pPacketInfo Information on the type of incoming MQTT packet.
  * @param[in] pDeserializedInfo Deserialized information from incoming packet.
  */
-typedef void (* MQTTEventCallback_t )( MQTTContext_t * pContext,
-                                       MQTTPacketInfo_t * pPacketInfo,
-                                       MQTTDeserializedInfo_t * pDeserializedInfo );
+typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
+                                       struct MQTTPacketInfo * pPacketInfo,
+                                       struct MQTTDeserializedInfo * pDeserializedInfo );
 
 /**
  * @brief Values indicating if an MQTT connection exists.
@@ -106,16 +106,6 @@ typedef enum MQTTPubAckType
     MQTTPubcomp /**< @brief PUBCOMPs are sent in response to a PUBREL. */
 } MQTTPubAckType_t;
 
-/**
- * @brief An element of the state engine records for QoS 1/2 publishes.
- */
-struct MQTTPubAckInfo
-{
-    uint16_t packetId;               /**< @brief The packet ID of the original PUBLISH. */
-    MQTTQoS_t qos;                   /**< @brief The QoS of the original PUBLISH. */
-    MQTTPublishState_t publishState; /**< @brief The current state of the publish process. */
-};
-
 /**
  * @brief The status codes in the SUBACK response to a subscription request.
  */
@@ -127,10 +117,20 @@ typedef enum MQTTSubAckStatus
     MQTTSubAckFailure = 0x80      /**< @brief Failure. */
 } MQTTSubAckStatus_t;
 
+/**
+ * @brief An element of the state engine records for QoS 1 or Qos 2 publishes.
+ */
+typedef struct MQTTPubAckInfo
+{
+    uint16_t packetId;               /**< @brief The packet ID of the original PUBLISH. */
+    MQTTQoS_t qos;                   /**< @brief The QoS of the original PUBLISH. */
+    MQTTPublishState_t publishState; /**< @brief The current state of the publish process. */
+} MQTTPubAckInfo_t;
+
 /**
  * @brief A struct representing an MQTT connection.
  */
-struct MQTTContext
+typedef struct MQTTContext
 {
     /**
      * @brief State engine records for outgoing publishes.
@@ -187,34 +187,37 @@ struct MQTTContext
     uint16_t keepAliveIntervalSec; /**< @brief Keep Alive interval. */
     uint32_t pingReqSendTimeMs;    /**< @brief Timestamp of the last sent PINGREQ. */
     bool waitingForPingResp;       /**< @brief If the library is currently awaiting a PINGRESP. */
-};
+} MQTTContext_t;
 
 /**
  * @brief Struct to hold deserialized packet information for an #MQTTEventCallback_t
  * callback.
  */
-struct MQTTDeserializedInfo
+typedef struct MQTTDeserializedInfo
 {
     uint16_t packetIdentifier;          /**< @brief Packet ID of deserialized packet. */
     MQTTPublishInfo_t * pPublishInfo;   /**< @brief Pointer to deserialized publish info. */
     MQTTStatus_t deserializationResult; /**< @brief Return code of deserialization. */
-};
+} MQTTDeserializedInfo_t;
 
 /**
  * @brief Initialize an MQTT context.
  *
- * This function must be called on an MQTT context before any other function.
+ * This function must be called on a #MQTTContext_t before any other function.
  *
- * @note The getTime callback function must be defined. If there is no time
- * implementation, it is the responsibility of the application to provide a
- * dummy function to always return 0, and provide 0 timeouts for functions. This
- * will ensure all time based functions will run for a single iteration.
+ * @note The #MQTTGetCurrentTimeFunc_t callback function must be defined. If
+ * there is no time implementation, it is the responsibility of the application
+ * to provide a dummy function to always return 0, and provide 0 timeouts for
+ * functions. This will ensure all time based functions will run for a single
+ * iteration.
  *
  * @brief param[in] pContext The context to initialize.
- * @brief param[in] pTransportInterface The transport interface to use with the context.
- * @brief param[in] getTimeFunction The time utility function to use with the context.
- * @brief param[in] userCallback The user callback to use with the context to notify about
- * incoming packet events.
+ * @brief param[in] pTransportInterface The transport interface to use with the
+ * context.
+ * @brief param[in] getTimeFunction The time utility function to use with the
+ * context.
+ * @brief param[in] userCallback The user callback to use with the context to
+ * notify about incoming packet events.
  * @brief param[in] pNetworkBuffer Network buffer provided for the context.
  *
  * @return #MQTTBadParameter if invalid parameters are passed;
@@ -276,12 +279,12 @@ MQTTStatus_t MQTT_Init( MQTTContext_t * pContext,
  *
  * The maximum time this function waits for a CONNACK is decided in one of the
  * following ways:
- * 1. If #timeoutMs is greater than 0:
- *    #getTime is used to ensure that the function does not wait more than #timeoutMs
- *    for CONNACK.
- * 2. If #timeoutMs is 0:
- *    The network receive for CONNACK is retried up to the number of times configured
- *    by #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.
+ * 1. If @p timeoutMs is greater than 0:
+ *    #MQTTContext_t.getTime is used to ensure that the function does not wait
+ *    more than @p timeoutMs for CONNACK.
+ * 2. If @p timeoutMs is 0:
+ *    The network receive for CONNACK is retried up to the number of times
+ *    configured by #MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.
  *
  * @param[in] pContext Initialized MQTT context.
  * @param[in] pConnectInfo MQTT CONNECT packet information.
@@ -299,7 +302,7 @@ MQTTStatus_t MQTT_Init( MQTTContext_t * pContext,
  * #MQTTSendFailed if transport send failed;
  * #MQTTRecvFailed if transport receive failed for CONNACK;
  * #MQTTNoDataAvailable if no data available to receive in transport until
- * the #timeoutMs for CONNACK;
+ * the @p timeoutMs for CONNACK;
  * #MQTTSuccess otherwise.
  *
  * @note This API may spend more time than provided in the timeoutMS parameters in
@@ -379,7 +382,7 @@ MQTTStatus_t MQTT_Connect( MQTTContext_t * pContext,
  * @param[in] pContext Initialized MQTT context.
  * @param[in] pSubscriptionList List of MQTT subscription info.
  * @param[in] subscriptionCount The number of elements in pSubscriptionList.
- * @param[in] packetId packet ID generated by #MQTT_GetPacketId.
+ * @param[in] packetId Packet ID generated by #MQTT_GetPacketId.
  *
  * @return #MQTTNoMemory if the #MQTTContext_t.networkBuffer is too small to
  * hold the MQTT packet;
@@ -668,7 +671,7 @@ uint16_t MQTT_GetPacketId( MQTTContext_t * pContext );
  *  - 0x01 - Success - Maximum QoS 1
  *  - 0x02 - Success - Maximum QoS 2
  *  - 0x80 - Failure
- * Refer to @ref MQTTSubAckStatus for the status codes.
+ * Refer to #MQTTSubAckStatus_t for the status codes.
  *
  * @param[in] pSubackPacket The SUBACK packet whose payload is to be parsed.
  * @param[out] pPayloadStart This is populated with the starting address

libraries/standard/mqtt/include/mqtt_lightweight.h

@@ -19,12 +19,23 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * @file mqtt_lightweight.h
+ * @brief User-facing functions for serializing and deserializing MQTT 3.1.1
+ * packets. This header should be included for building a lightweight MQTT
+ * client bypassing the managed CSDK MQTT library API in mqtt.h.
+ */
 #ifndef MQTT_LIGHTWEIGHT_H
 #define MQTT_LIGHTWEIGHT_H
 
 #include <stddef.h>
 #include <stdint.h>
 
+/**
+ * @cond DOXYGEN_IGNORE
+ * Doxygen should ignore this section.
+ */
+
 /* bool is defined in only C99+. */
 #if defined( __cplusplus ) || ( defined( __STDC_VERSION__ ) && ( __STDC_VERSION__ >= 199901L ) )
     #include <stdbool.h>
@@ -33,6 +44,7 @@
     #define false    ( int8_t ) 0
     #define true     ( int8_t ) 1
 #endif
+/** @endcond */
 
 /* Include config file before other headers. */
 #include "mqtt_config.h"
@@ -55,26 +67,17 @@
 #define MQTT_PACKET_TYPE_PINGRESP       ( ( uint8_t ) 0xD0U )  /**< @brief PINGRESP (server-to-client). */
 #define MQTT_PACKET_TYPE_DISCONNECT     ( ( uint8_t ) 0xE0U )  /**< @brief DISCONNECT (client-to-server). */
 
-
 /**
  * @brief The size of MQTT PUBACK, PUBREC, PUBREL, and PUBCOMP packets, per MQTT spec.
  */
 #define MQTT_PUBLISH_ACK_PACKET_SIZE    ( 4UL )
 
+/* Structures defined in this file. */
 struct MQTTFixedBuffer;
-typedef struct MQTTFixedBuffer     MQTTFixedBuffer_t;
-
 struct MQTTConnectInfo;
-typedef struct MQTTConnectInfo     MQTTConnectInfo_t;
-
 struct MQTTSubscribeInfo;
-typedef struct MQTTSubscribeInfo   MQTTSubscribeInfo_t;
-
-struct MqttPublishInfo;
-typedef struct MqttPublishInfo     MQTTPublishInfo_t;
-
+struct MQTTPublishInfo;
 struct MQTTPacketInfo;
-typedef struct MQTTPacketInfo      MQTTPacketInfo_t;
 
 /**
  * @brief Return codes from MQTT functions.
@@ -110,16 +113,16 @@ typedef enum MQTTQoS
  * These buffers are not copied and must remain in scope for the duration of the
  * MQTT operation.
  */
-struct MQTTFixedBuffer
+typedef struct MQTTFixedBuffer
 {
     uint8_t * pBuffer; /**< @brief Pointer to buffer. */
     size_t size;       /**< @brief Size of buffer. */
-};
+} MQTTFixedBuffer_t;
 
 /**
  * @brief MQTT CONNECT packet parameters.
  */
-struct MQTTConnectInfo
+typedef struct MQTTConnectInfo
 {
     /**
      * @brief Whether to establish a new, clean session or resume a previous session.
@@ -160,12 +163,12 @@ struct MQTTConnectInfo
      * @brief Length of MQTT password. Set to 0 if not used.
      */
     uint16_t passwordLength;
-};
+} MQTTConnectInfo_t;
 
 /**
  * @brief MQTT SUBSCRIBE packet parameters.
  */
-struct MQTTSubscribeInfo
+typedef struct MQTTSubscribeInfo
 {
     /**
      * @brief Quality of Service for subscription.
@@ -181,12 +184,12 @@ struct MQTTSubscribeInfo
      * @brief Length of subscription topic filter.
      */
     uint16_t topicFilterLength;
-};
+} MQTTSubscribeInfo_t;
 
 /**
  * @brief MQTT PUBLISH packet parameters.
  */
-struct MqttPublishInfo
+typedef struct MQTTPublishInfo
 {
     /**
      * @brief Quality of Service for message.
@@ -222,12 +225,12 @@ struct MqttPublishInfo
      * @brief Message payload length.
      */
     size_t payloadLength;
-};
+} MQTTPublishInfo_t;
 
 /**
  * @brief MQTT incoming packet parameters.
  */
-struct MQTTPacketInfo
+typedef struct MQTTPacketInfo
 {
     /**
      * @brief Type of incoming MQTT packet.
@@ -243,7 +246,7 @@ struct MQTTPacketInfo
      * @brief Length of remaining serialized data.
      */
     size_t remainingLength;
-};
+} MQTTPacketInfo_t;
 
 /**
  * @brief Get the size and Remaining Length of an MQTT CONNECT packet.