Resolve memory stats, spell check, doxygen example and comments

Author: Dakshit Babbar

docs/doxygen/include/size_table.md

@@ -9,8 +9,8 @@
     </tr>
     <tr>
         <td>core_mqtt.c</td>
-        <td><center>4.4K</center></td>
-        <td><center>3.8K</center></td>
+        <td><center>4.9K</center></td>
+        <td><center>4.2K</center></td>
     </tr>
     <tr>
         <td>core_mqtt_state.c</td>
@@ -19,12 +19,12 @@
     </tr>
     <tr>
         <td>core_mqtt_serializer.c</td>
-        <td><center>2.8K</center></td>
-        <td><center>2.2K</center></td>
+        <td><center>2.9K</center></td>
+        <td><center>2.3K</center></td>
     </tr>
     <tr>
         <td><b>Total estimates</b></td>
-        <td><b><center>8.9K</center></b></td>
-        <td><b><center>7.3K</center></b></td>
+        <td><b><center>9.5K</center></b></td>
+        <td><b><center>7.8K</center></b></td>
     </tr>
 </table>

source/core_mqtt.c

@@ -1606,7 +1606,7 @@ static MQTTStatus_t handlePublishAcks( MQTTContext_t * pContext,
             ( pContext->clearFunction != NULL ) &&
             ( pContext->clearFunction( pContext, packetIdentifier ) != true ) )
         {
-            LogWarn( ( "Clear callback function failed\n" ) );
+            LogWarn( ( "Failed to clear copied publish on receiving an ack.\n" ) );
         }
     }
 
@@ -2204,21 +2204,26 @@ static MQTTStatus_t sendPublishWithoutCopy( MQTTContext_t * pContext,
         totalMessageLength += pPublishInfo->payloadLength;
     }
 
-    /* store a copy of the publish with duplicate flag set for retransmission purposes */
+    /* if not already set, set the dup flag before storing a copy of the publish 
+     * this is because on retrieving back this copy we will get it in the form of an 
+     * array of TransportOutVector_t that holds the data in a const pointer which cannot be 
+     * changed after retrieving.*/
     if( pPublishInfo->dup != true )
     {
         MQTT_UpdateDuplicatePublishFlag( pMqttHeader, true );
 
         dupFlagChanged = true;
     }
 
+    /* store a copy of the publish for retransmission purposes */
     if( ( pPublishInfo->qos > MQTTQoS0 ) &&
         ( pContext->storeFunction != NULL ) &&
         ( pContext->storeFunction( pContext, packetId, pIoVector, ioVectorLength ) != true ) )
     {
         status = MQTTPublishStoreFailed;
     }
 
+    /* change the value of the dup flag to its original, if it was changed */
     if( dupFlagChanged )
     {
         MQTT_UpdateDuplicatePublishFlag( pMqttHeader, false );
@@ -2545,7 +2550,7 @@ static MQTTStatus_t handleUncleanSessionResumption( MQTTContext_t * pContext )
             status = MQTTPublishRetrieveFailed;
         }
 
-        /* Resend all the PUBLISH for which PUBCK/PUBREC is not received
+        /* Resend all the PUBLISH for which PUBACK/PUBREC is not received 
          * after session is reestablished. */
         while( ( packetId != MQTT_PACKET_ID_INVALID ) &&
                ( status == MQTTSuccess ) )
@@ -2775,10 +2780,10 @@ MQTTStatus_t MQTT_InitStatefulQoS( MQTTContext_t * pContext,
 /*-----------------------------------------------------------*/
 
 MQTTStatus_t MQTT_InitRetransmits( MQTTContext_t * pContext,
-                                   MQTTRetransmitStorePacket storeFunction,
-                                   MQTTRetransmitRetrievePacket retrieveFunction,
-                                   MQTTRetransmitClearPacket clearFunction,
-                                   MQTTRetransmitClearAllPackets clearAllFunction )
+                                   MQTTStorePacketForRetransmit storeFunction,
+                                   MQTTRetrievePacketForRetransmit retrieveFunction,
+                                   MQTTClearPacketForRetransmit clearFunction,
+                                   MQTTClearAllPacketsForRetransmit clearAllFunction )
 {
     MQTTStatus_t status = MQTTSuccess;
 

source/core_mqtt_serializer.c

@@ -102,7 +102,7 @@
 #define UINT8_SET_BIT( x, position )      ( ( x ) = ( uint8_t ) ( ( x ) | ( 0x01U << ( position ) ) ) )
 
 /**
- * @brief Set a bit in an 8-bit unsigned integer.
+ * @brief Clear a bit in an 8-bit unsigned integer.
  */
 #define UINT8_CLEAR_BIT( x, position )    ( ( x ) = ( uint8_t ) ( ( x ) & ( ~( 0x01U << ( position ) ) ) ) )
 

source/include/core_mqtt.h

@@ -102,7 +102,7 @@ typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
                                        struct MQTTDeserializedInfo * pDeserializedInfo );
 
 /**
- * @brief User defined API used to store outgoing publishes. Used to track any publish
+ * @brief User defined callback used to store outgoing publishes. Used to track any publish 
  * retransmit on an unclean session connection.
  *
  * @param[in] pContext Initialised MQTT Context.
@@ -113,14 +113,14 @@ typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
  * @return True if the copy is successful else false.
  */
 /* @[define_mqtt_retransmitstorepacket] */
-typedef bool ( * MQTTRetransmitStorePacket)( struct MQTTContext * pContext,
-                                             uint16_t packetId,
-                                             TransportOutVector_t * pIoVec,
-                                             size_t ioVecCount );
+typedef bool ( * MQTTStorePacketForRetransmit)( struct MQTTContext * pContext,
+                                            uint16_t packetId,
+                                            TransportOutVector_t * pIoVec,
+                                            size_t ioVecCount );
 /* @[define_mqtt_retransmitstorepacket] */
 
 /**
- * @brief User defined API used to retreive a copied publish for resend operation. Used to
+ * @brief User defined callback used to retreive a copied publish for resend operation. Used to 
  * track any publish retransmit on an unclean session connection.
  *
  * @param[in] pContext Initialised MQTT Context.
@@ -131,14 +131,14 @@ typedef bool ( * MQTTRetransmitStorePacket)( struct MQTTContext * pContext,
  * @return True if the retreive is successful else false.
  */
 /* @[define_mqtt_retransmitretrievepacket] */
-typedef bool ( * MQTTRetransmitRetrievePacket)( struct MQTTContext * pContext,
-                                                uint16_t packetId,
-                                                TransportOutVector_t ** pIoVec,
-                                                size_t * ioVecCount );
+typedef bool ( * MQTTRetrievePacketForRetransmit)( struct MQTTContext * pContext,
+                                            uint16_t packetId,
+                                            TransportOutVector_t ** pIoVec,
+                                            size_t * ioVecCount );
 /* @[define_mqtt_retransmitretrievepacket] */
 
 /**
- * @brief User defined API used to clear a particular copied publish packet. Used to
+ * @brief User defined callback used to clear a particular copied publish packet. Used to 
  * track any publish retransmit on an unclean session connection.
  *
  * @param[in] pContext Initialised MQTT Context.
@@ -147,20 +147,20 @@ typedef bool ( * MQTTRetransmitRetrievePacket)( struct MQTTContext * pContext,
  * @return True if the clear is successful else false.
  */
 /* @[define_mqtt_retransmitclearpacket] */
-typedef bool (* MQTTRetransmitClearPacket)( struct MQTTContext * pContext,
-                                            uint16_t packetId );
+typedef bool (*MQTTClearPacketForRetransmit)( struct MQTTContext * pContext,
+                                         uint16_t packetId );
 /* @[define_mqtt_retransmitclearpacket] */
 
 /**
- * @brief User defined API used to clear all copied publish packets. Used to
+ * @brief User defined callback used to clear all copied publish packets. Used to 
  * when connecting with a clean session.
  *
  * @param[in] pContext Initialised MQTT Context.
  *
  * @return True if the clear all is successful else false.
  */
 /* @[define_mqtt_retransmitclearallpackets] */
-typedef bool (* MQTTRetransmitClearAllPackets)( struct MQTTContext * pContext );
+typedef bool (*MQTTClearAllPacketsForRetransmit)( struct MQTTContext * pContext );
 /* @[define_mqtt_retransmitclearallpackets] */
 
 /**
@@ -313,22 +313,22 @@ typedef struct MQTTContext
     /**
      * @brief User defined API used to store outgoing publishes.
      */
-    MQTTRetransmitStorePacket storeFunction;
+    MQTTStorePacketForRetransmit storeFunction;
 
     /**
      * @brief User defined API used to retreive a copied publish for resend operation.
      */
-    MQTTRetransmitRetrievePacket retrieveFunction;
+    MQTTRetrievePacketForRetransmit retrieveFunction;
 
     /**
      * @brief User defined API used to clear a particular copied publish packet.
      */
-    MQTTRetransmitClearPacket clearFunction;
+    MQTTClearPacketForRetransmit clearFunction;   
 
     /**
      * @brief User defined API used to clear all copied publish packets.
      */
-    MQTTRetransmitClearAllPackets clearAllFunction;
+    MQTTClearAllPacketsForRetransmit clearAllFunction;
 } MQTTContext_t;
 
 /**
@@ -510,16 +510,86 @@ MQTTStatus_t MQTT_InitStatefulQoS( MQTTContext_t * pContext,
  *
  * @return #MQTTBadParameter if invalid parameters are passed;
  * #MQTTSuccess otherwise.
+ * 
+ * <b>Example</b>
+ * @code{c}
+ *
+ * // Function for obtaining a timestamp.
+ * uint32_t getTimeStampMs();
+ * // Callback function for receiving packets.
+ * void eventCallback(
+ *      MQTTContext_t * pContext,
+ *      MQTTPacketInfo_t * pPacketInfo,
+ *      MQTTDeserializedInfo_t * pDeserializedInfo
+ * );
+ * // Network send.
+ * int32_t networkSend( NetworkContext_t * pContext, const void * pBuffer, size_t bytes );
+ * // Network receive.
+ * int32_t networkRecv( NetworkContext_t * pContext, void * pBuffer, size_t bytes );
+ * // User defined callback used to store outgoing publishes
+ * bool publishStoreCallback(struct MQTTContext* pContext,
+ *                           uint16_t packetId,
+ *                           TransportOutVector_t* pIoVec,
+ *                           size_t ioVecCount);
+ * // User defined callback used to retreive a copied publish for resend operation
+ * bool publishRetrieveCallback(struct MQTTContext* pContext,
+ *                              uint16_t packetId,
+ *                              TransportOutVector_t** pIoVec,
+ *                              size_t* ioVecCount);
+ * // User defined callback used to clear a particular copied publish packet
+ * bool publishClearCallback(struct MQTTContext* pContext,
+ *                           uint16_t packetId);
+ * // User defined callback used to clear all copied publish packets
+ * bool publishClearAllCallback(struct MQTTContext* pContext);
+ *
+ * MQTTContext_t mqttContext;
+ * TransportInterface_t transport;
+ * MQTTFixedBuffer_t fixedBuffer;
+ * uint8_t buffer[ 1024 ];
+ * const size_t outgoingPublishCount = 30;
+ * MQTTPubAckInfo_t outgoingPublishes[ outgoingPublishCount ];
+ *
+ * // Clear context.
+ * memset( ( void * ) &mqttContext, 0x00, sizeof( MQTTContext_t ) );
+ *
+ * // Set transport interface members.
+ * transport.pNetworkContext = &someTransportContext;
+ * transport.send = networkSend;
+ * transport.recv = networkRecv;
+ *
+ * // Set buffer members.
+ * fixedBuffer.pBuffer = buffer;
+ * fixedBuffer.size = 1024;
+ *
+ * status = MQTT_Init( &mqttContext, &transport, getTimeStampMs, eventCallback, &fixedBuffer );
  *
+ * if( status == MQTTSuccess )
+ * {
+ *      // We do not expect any incoming publishes in this example, therefore the incoming
+ *      // publish pointer is NULL and the count is zero.
+ *      status = MQTT_InitStatefulQoS( &mqttContext, outgoingPublishes, outgoingPublishCount, NULL, 0 );
+ *
+ *      // Now QoS1 and/or QoS2 publishes can be sent with this context.
+ * }
+ * 
+ * if( status == MQTTSuccess )
+ * {
+ *      status = MQTT_InitRetransmits( &mqttContext, publishStoreCallback, 
+ *                                                   publishRetrieveCallback, 
+ *                                                   publishClearCallback, 
+ *                                                   publishClearAllCallback );
+ *
+ *      // Now unacked Publishes can be resent on an unclean session resumption.
+ * }
  * @endcode
  */
 
 /* @[declare_mqtt_initretransmits] */
 MQTTStatus_t MQTT_InitRetransmits( MQTTContext_t * pContext,
-                                   MQTTRetransmitStorePacket storeFunction,
-                                   MQTTRetransmitRetrievePacket retrieveFunction,
-                                   MQTTRetransmitClearPacket clearFunction,
-                                   MQTTRetransmitClearAllPackets clearAllFunction );
+                                   MQTTStorePacketForRetransmit storeFunction,
+                                   MQTTRetrievePacketForRetransmit retrieveFunction,
+                                   MQTTClearPacketForRetransmit clearFunction,
+                                   MQTTClearAllPacketsForRetransmit clearAllFunction );
 /* @[declare_mqtt_initretransmits] */
 
 /**