Adding doxygen documentation. Fixing a few doc issues.

MQTTClient-C/src/MQTTClient.h

@@ -163,8 +163,8 @@ typedef struct MQTTSubackData
 
 /**
  * @brief Data structure containing information about a published message.
- * @note This structure is used for both QoS1 (PUBACK) and QoS2 (PUBCOMP) messages.
- * @note The `id` field is omitted as it is already present in the `MQTTMessage` structure.
+ * @remark This structure is used for both QoS1 (PUBACK) and QoS2 (PUBCOMP) messages.
+ * @remark The `id` field is omitted as it is already present in the `MQTTMessage` structure.
  */
 typedef struct MQTTPubDoneData
 {
@@ -180,7 +180,7 @@ typedef struct MQTTPubDoneData
 
 /**
  * @brief Callback type for handling incoming messages.
- * @note Separate callbacks can be used for each subscription filter.
+ * @remark Separate callbacks can be used for each subscription filter.
  * 
  * @param received The received message.
  */
@@ -189,7 +189,7 @@ typedef void (*messageHandler)(MessageData* received);
 #if defined(MQTTV5)
 /**
  * @brief Callback type used for asynchronous MQTTv5 DISCONNECT and AUTH.
- * @note Separate callbacks should be used for each control message type.
+ * @remark Separate callbacks should be used for each control message type.
  * 
  * @param properties The MQTTv5 message properties.
  * @param reasonCode The MQTTv5 reason code.
@@ -266,7 +266,7 @@ DLLExport void MQTTClientInit(MQTTClient* client, Network* network, unsigned int
  * @param client The `MQTTClient` object to use.
  * @param options The connect options.
  * @param connack CONNACK response information.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTConnectWithResults(MQTTClient* client, MQTTPacket_connectData* options,
     MQTTConnackData* connack);
@@ -277,7 +277,7 @@ DLLExport int MQTTConnectWithResults(MQTTClient* client, MQTTPacket_connectData*
  * 
  * @param client The `MQTTClient` object to use.
  * @param options The connect options.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTConnect(MQTTClient* client, MQTTPacket_connectData* options);
 
@@ -287,19 +287,19 @@ DLLExport int MQTTConnect(MQTTClient* client, MQTTPacket_connectData* options);
  * @param client The `MQTTClient` object to use. 
  * @param topicName The topic to publish to.
  * @param message The `MQTTMessage` message to send.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTPublish(MQTTClient* client, const char* topicName, MQTTMessage* message);
 
 /**
  * @brief MQTT Publish - send an MQTT publish packet and wait for all acks (PUBACK or PUBCOMP) to complete for all QoSs.
- * @note This function blocks until the QoS1 PUBACK or QoS2 PUBCOMP is received.
+ * @remark This function blocks until the QoS1 PUBACK or QoS2 PUBCOMP is received.
  * 
  * @param client The `MQTTClient` object to use.
  * @param topic The topic to publish to.
  * @param message The message to send.
  * @param ack Acknowledgement information (from either a PUBACK or PUBCOMP message).
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTPublishWithResults(MQTTClient* client, const char* topic, MQTTMessage* message, MQTTPubDoneData* ack);
 
@@ -309,7 +309,7 @@ DLLExport int MQTTPublishWithResults(MQTTClient* client, const char* topic, MQTT
  * @param client The `MQTTClient` object to use.
  * @param topicFilter The topic filter for the message handler.
  * @param messageHandler The message handler function or NULL to remove.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTSetMessageHandler(MQTTClient* client, const char* topicFilter, messageHandler messageHandler);
 
@@ -320,7 +320,7 @@ DLLExport int MQTTSetMessageHandler(MQTTClient* client, const char* topicFilter,
  * @param topicFilter The topic filter to subscribe.
  * @param requestedQoS The requested QoS.
  * @param messageHandler The message handler function. If `NULL`, it will remove an existing messageHandler for this topicFilter.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTSubscribe(MQTTClient* client, const char* topicFilter, enum MQTTQoS requestedQoS, messageHandler messageHandler);
 
@@ -329,26 +329,28 @@ DLLExport int MQTTSubscribe(MQTTClient* client, const char* topicFilter, enum MQ
  * 
  * @param client The `MQTTClient` object to use.
  * @param topicFilter The topic filter to subscribe.
+ * @param requestedQoS The requested QoS.
  * @param messageHandler The message handler function. If `NULL`, it will remove an existing messageHandler for this topicFilter.
  * @param suback Subscription acknowledgement information.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
-DLLExport int MQTTSubscribeWithResults(MQTTClient* client, const char* topicFilter, enum MQTTQoS qos, messageHandler messageHandler, MQTTSubackData* suback);
+DLLExport int MQTTSubscribeWithResults(MQTTClient* client, const char* topicFilter, enum MQTTQoS requestedQoS, 
+  messageHandler messageHandler, MQTTSubackData* suback);
 
 /**
  * @brief MQTT Unsubscribe - send an MQTT unsubscribe packet and wait for UNSUBACK before returning.
  * 
  * @param client The `MQTTClient` object to use.
  * @param topicFilter The topic filter to unsubscribe.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTUnsubscribe(MQTTClient* client, const char* topicFilter);
 
 /**
  * @brief MQTT Disconnect - send an MQTT disconnect packet and close the connection.
  * 
  * @param client The `MQTTClient` object to use.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTDisconnect(MQTTClient* client);
 
@@ -360,7 +362,7 @@ DLLExport int MQTTDisconnect(MQTTClient* client);
  * 
  * @param client The `MQTTClient` object to use.
  * @param timeout_ms The time to wait, in milliseconds.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTYield(MQTTClient* client, int timeout_ms);
 
@@ -378,7 +380,7 @@ DLLExport int MQTTIsConnected(MQTTClient* client);
  * @note After this, `MQTTYield` should not be called.
  * 
  * @param client The `MQTTClient` object to use.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTStartTask(MQTTClient* client);
 #endif

MQTTClient-C/src/V5/MQTTV5Client.h

@@ -32,7 +32,7 @@ typedef struct MQTTV5UnsubackData
 {
     /// @brief The MQTTv5 message properties.
     MQTTProperties* properties;
-    /// @brief The MQTT reason code.
+    /// @brief The MQTTv5 reason code.
     enum MQTTReasonCodes reasonCode;
 } MQTTV5UnsubackData;
 
@@ -49,10 +49,10 @@ typedef struct MQTTV5UnsubackData
  * @param recvProperties The MQTTv5 receive properties. This allocation will be used for all MQTTv5 packets.
  * @param truncateRecvProperties If true, the MQTTv5 properties will be truncated if they do not fit in the `recvProperties` buffer.
  * 
- * @note If `recvProperties` does not contain sufficient space for the received properties and `truncateRecvProperties` is false, 
+ * @remark If `recvProperties` does not contain sufficient space for the received properties and `truncateRecvProperties` is false, 
  *       `MQTTYield` will fail with `MQTTCLIENT_BUFFER_OVERFLOW`.
  * 
- * @note If the `MQTTClient` is initialized with `MQTTV5ClientInit`, any of the non-versioned functions (e.g. `MQTTPublish`) will
+ * @remark If the `MQTTClient` is initialized with `MQTTV5ClientInit`, any of the non-versioned functions (e.g. `MQTTPublish`) will
  *       work as expected. However, v5 functions (e.g. `MQTTV5Publish`) must be used to access MQTTv5 features.
  */
 DLLExport void MQTTV5ClientInit(MQTTClient* client, Network* network, unsigned int command_timeout_ms,
@@ -68,7 +68,7 @@ DLLExport void MQTTV5ClientInit(MQTTClient* client, Network* network, unsigned i
  * @param connectProperties The MQTTv5 connect properties.
  * @param willProperties The MQTTv5 will properties.
  * @param connack CONNACK response information.
- * @return 0 on success. If negative, an `MQTTClientReturnCode` indicating success or failure. 
+ * @return 0 on success. If negative, an #MQTTClientReturnCode indicating success or failure. 
  *         If positive, the `MQTTReasonCodes` returned by the server.
  */
 DLLExport int MQTTV5ConnectWithResults(MQTTClient* client, MQTTPacket_connectData* options,
@@ -82,7 +82,7 @@ DLLExport int MQTTV5ConnectWithResults(MQTTClient* client, MQTTPacket_connectDat
  * @param options The connect options.
  * @param connectProperties The MQTTv5 connect properties.
  * @param willProperties The MQTTv5 will properties.
- * @return 0 on success. If negative, an `MQTTClientReturnCode` indicating success or failure. 
+ * @return 0 on success. If negative, an #MQTTClientReturnCode indicating success or failure. 
  *         If positive, the `MQTTReasonCodes` returned by the server.
  */
 DLLExport int MQTTV5Connect(MQTTClient* client, MQTTPacket_connectData* options, 
@@ -95,7 +95,7 @@ DLLExport int MQTTV5Connect(MQTTClient* client, MQTTPacket_connectData* options,
  * @param topicName The topic to publish to.
  * @param message The `MQTTMessage` message to send.
  * @param properties The MQTTv5 publish properties.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5Publish(MQTTClient* client, const char* topicName, MQTTMessage* message, 
   MQTTProperties* properties);
@@ -109,7 +109,7 @@ DLLExport int MQTTV5Publish(MQTTClient* client, const char* topicName, MQTTMessa
  * @param message The message to send.
  * @param properties The MQTTv5 publish properties.
  * @param ack Acknowledgement information (from either a PUBACK or PUBCOMP message).
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5PublishWithResults(MQTTClient* client, const char* topic, MQTTMessage* message, 
   MQTTProperties* properties, MQTTPubDoneData* ack);
@@ -120,7 +120,7 @@ DLLExport int MQTTV5PublishWithResults(MQTTClient* client, const char* topic, MQ
  * @param client The `MQTTClient` object to use.
  * @param topicFilter The topic filter for the message handler.
  * @param messageHandler The message handler function or NULL to remove.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5SetMessageHandler(MQTTClient* client, const char* topicFilter, messageHandler messageHandler);
 
@@ -130,7 +130,7 @@ DLLExport int MQTTV5SetMessageHandler(MQTTClient* client, const char* topicFilte
  * @param client The `MQTTClient` object to use.
  * @param reasonCode The MQTTv5 reason code.
  * @param properties The MQTTv5 properties.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5Auth(MQTTClient* client, unsigned char reasonCode, MQTTProperties* properties);
 
@@ -139,7 +139,7 @@ DLLExport int MQTTV5Auth(MQTTClient* client, unsigned char reasonCode, MQTTPrope
  * 
  * @param client The `MQTTClient` object to use.
  * @param authHandler The AUTH receive handler function or NULL to remove.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5SetAuthHandler(MQTTClient* client, controlHandler authHandler);
 
@@ -152,7 +152,7 @@ DLLExport int MQTTV5SetAuthHandler(MQTTClient* client, controlHandler authHandle
  * @param properties The MQTTv5 subscribe properties.
  * @param options The MQTTv5 subscribe options.
  * @param messageHandler The message handler function. If `NULL`, it will remove an existing messageHandler for this topicFilter.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5Subscribe(MQTTClient* client, const char* topicFilter, enum MQTTQoS requestedQoS, 
   MQTTProperties* properties, MQTTSubscribe_options options, messageHandler messageHandler);
@@ -167,7 +167,7 @@ DLLExport int MQTTV5Subscribe(MQTTClient* client, const char* topicFilter, enum
  * @param options The MQTTv5 subscribe options.
  * @param messageHandler The message handler function. If `NULL`, it will remove an existing messageHandler for this topicFilter.
  * @param suback Subscription acknowledgement information.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5SubscribeWithResults(MQTTClient* client, const char* topicFilter, enum MQTTQoS requestedQoS, 
   MQTTProperties* properties, MQTTSubscribe_options options, messageHandler messageHandler, MQTTSubackData* suback);
@@ -178,7 +178,7 @@ DLLExport int MQTTV5SubscribeWithResults(MQTTClient* client, const char* topicFi
  * @param client The `MQTTClient` object to use.
  * @param topicFilter The topic filter to unsubscribe.
  * @param properties The MQTTv5 unsubscribe properties.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5Unsubscribe(MQTTClient* client, const char* topicFilter, MQTTProperties* properties);
 
@@ -189,7 +189,7 @@ DLLExport int MQTTV5Unsubscribe(MQTTClient* client, const char* topicFilter, MQT
  * @param topicFilter The topic filter to unsubscribe.
  * @param properties The MQTTv5 unsubscribe properties.
  * @param unsuback Unsubscription acknowledgement information.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5UnsubscribeWithResults(MQTTClient* client, const char* topicFilter, MQTTProperties* properties, 
   MQTTV5UnsubackData* unsuback);
@@ -200,7 +200,7 @@ DLLExport int MQTTV5UnsubscribeWithResults(MQTTClient* client, const char* topic
  * @param client The `MQTTClient` object to use.
  * @param reasonCode The MQTTv5 reason code.
  * @param properties The MQTTv5 disconnect properties.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5Disconnect(MQTTClient* client, unsigned char reasonCode, MQTTProperties* properties);
 
@@ -209,7 +209,7 @@ DLLExport int MQTTV5Disconnect(MQTTClient* client, unsigned char reasonCode, MQT
  * 
  * @param client The `MQTTClient` object to use.
  * @param disconnectHandler The AUTH receive handler function or NULL to remove.
- * @return An `MQTTClientReturnCode` indicating success or failure.
+ * @return An #MQTTClientReturnCode indicating success or failure.
  */
 DLLExport int MQTTV5SetDisconnectHandler(MQTTClient* client, controlHandler disconnectHandler);
 

doc/DoxyfileMQTTClient-C.in

@@ -162,7 +162,7 @@ FULL_PATH_NAMES        = NO
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        = MQTTClient-C/src MQTTClient-C/src/linux
+STRIP_FROM_PATH        = MQTTClient-C/src MQTTClient-C/src/linux MQTTClient/src/V5
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -790,7 +790,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = MQTTClient-C/src MQTTClient-C/src/linux
+INPUT                  = MQTTClient-C/src MQTTClient-C/src/linux MQTTClient-C/src/V5
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

doc/readme.md

@@ -0,0 +1,21 @@
+# Generating Paho Embedded Documentation
+
+## Requirements
+
+Download and install Doxygen. On Ubuntu, this can be insatalled using `sudo apt install doxygen`.
+
+## Genrating HTML documentation
+
+From the root of this repository:
+
+```
+# Generate the MQTTPacket Documentation
+doxygen ./doc/DoxyfileMQTTPacket.in
+
+# Generate the MQTTClient-C Documentation
+doxygen ./doc/DoxyfileMQTTClient-C.in
+
+# Generate the MQTTClient (C++) Documentation
+doxygen ./doc/DoxyfileMQTTClient.in
+
+```