Doxygen document updates

doc/DoxyfileV3AsyncAPI

@@ -545,7 +545,7 @@ GENERATE_DEPRECATEDLIST= YES
 # The ENABLED_SECTIONS tag can be used to enable conditional
 # documentation sections, marked by \if sectionname ... \endif.
 
-ENABLED_SECTIONS       =
+ENABLED_SECTIONS       = MQTTAsync_main
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines
 # the initial value of a variable or macro consists of for it to appear in
@@ -1520,7 +1520,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = __attribute__(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.

doc/DoxyfileV3ClientAPI

@@ -545,7 +545,7 @@ GENERATE_DEPRECATEDLIST= YES
 # The ENABLED_SECTIONS tag can be used to enable conditional
 # documentation sections, marked by \if sectionname ... \endif.
 
-ENABLED_SECTIONS       =
+ENABLED_SECTIONS       = MQTTClient_main
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines
 # the initial value of a variable or macro consists of for it to appear in
@@ -1520,7 +1520,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = __attribute__(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.

doc/DoxyfileV3ClientInternal

@@ -26,7 +26,7 @@ DOXYFILE_ENCODING      = UTF-8
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = "MQTT C Client"
+PROJECT_NAME           = "MQTT C Client Libraries Internals"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
@@ -545,7 +545,7 @@ GENERATE_DEPRECATEDLIST= YES
 # The ENABLED_SECTIONS tag can be used to enable conditional
 # documentation sections, marked by \if sectionname ... \endif.
 
-ENABLED_SECTIONS       =
+ENABLED_SECTIONS       = MQTTClient_internal
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines
 # the initial value of a variable or macro consists of for it to appear in

src/Log.c

@@ -15,6 +15,13 @@
  *    Ian Craggs - updates for the async client
  *******************************************************************************/
 
+/**
+ * @file
+ * \brief Logging and tracing module
+ *
+ * 
+ */
+
 #include "Log.h"
 #include "MQTTPacket.h"
 #include "MQTTProtocol.h"

src/MQTTAsync.c

@@ -16,6 +16,13 @@
  *    Ian Craggs - multiple server connection support
  *******************************************************************************/
 
+/**
+ * @file
+ * \brief Asynchronous API implementation
+ *
+ */
+
+
 #include <stdlib.h>
 #if !defined(WIN32)
 	#include <sys/time.h>

src/MQTTAsync.h

@@ -19,7 +19,9 @@
 /********************************************************************/
 
 /**
+ * @cond MQTTAsync_main
  * @mainpage Asynchronous MQTT client library for C
+ * 
  * © Copyright IBM Corp. 2009, 2013
  * 
  * @brief An Asynchronous MQTT client library for C.
@@ -34,17 +36,16 @@
  * API to the MQTT protocol using the programming language and platform of your 
  * choice. This can be time-consuming and error-prone.
  * 
- * To simplify writing MQTT client applications, WebSphere MQ Telemetry provides
- * C and Java client libraries that encapsulate the MQTT v3 protocol for a 
- * number of platforms. If you incorporate these libraries in your MQTT 
- * applications, a fully functional MQTT client can be written in a few lines of
- * code.  The information presented here documents the API provided by the IBM
- * Asynchronous MQTT Client library for C. 
+ * To simplify writing MQTT client applications, this library encapsulates
+ * the MQTT v3 protocol for you. Using this library enables a fully functional 
+ * MQTT client application to be written in a few lines of code.
+ * The information presented here documents the API provided
+ * by the Asynchronous MQTT Client library for C.
  * 
  * <b>Using the client</b><br>
  * Applications that use the client library typically use a similar structure:
  * <ul>
- * <li>Create a clent</li>
+ * <li>Create a client object</li>
  * <li>Set the options to connect to an MQTT server</li>
  * <li>Set up callback functions</li>
  * <li>Connect the client to an MQTT server</li>
@@ -67,7 +68,9 @@
  * <li>@ref async</li>
  * <li>@ref wildcard</li>
  * <li>@ref qos</li>
+ * <li>@ref tracing</li>
  * </ul>
+ * @endcond
  */
  
  
@@ -953,6 +956,7 @@ DLLExport MQTTAsync_nameValue* MQTTAsync_getVersionInfo();
 
 
 /**
+  * @cond MQTTAsync_main
   * @page async Threading 
   * The client application runs on several threads.
   * Processing of handshaking and maintaining
@@ -1349,6 +1353,118 @@ exit:
 }
               
   * @endcode
+* @page tracing Tracing
+  * 
+  * Runtime tracing can be controlled by environment variables or API calls.
+  *
+  * #### Environment variables
+  *
+  * Tracing is switched on by setting the MQTT_C_CLIENT_TRACE environment variable.  
+  * A value of ON, or stdout, prints to stdout, any other value is interpreted as a file name to use.
+  *
+  * The amount of trace detail is controlled with the MQTT_C_CLIENT_TRACE_LEVEL environment
+  * variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM
+  * (from least to most verbose).
+  *
+  * The variable MQTT_C_CLIENT_TRACE_MAX_LINES limits the number of lines of trace that are output
+  * to a file.  Two files are used at most, when they are full, the last one is overwritten with the
+  * new trace entries.  The default size is 1000 lines.
+  *
+  * #### Trace API calls
+  *
+  * MQTTAsync_traceCallback() is used to set a callback function which is called whenever trace
+  * information is available.  This will be the same information as that printed if the
+  * environment variables were used to control the trace.  
+  *
+  * The MQTTAsync_setTraceLevel() calls is used to set the maximum level of trace entries that will be
+  * passed to the callback function.  The levels are:
+  * 1. ::MQTTASYNC_TRACE_MAXIMUM
+  * 2. ::MQTTASYNC_TRACE_MEDIUM
+  * 3. ::MQTTASYNC_TRACE_MINIMUM
+  * 4. ::MQTTASYNC_TRACE_PROTOCOL
+  * 5. ::MQTTASYNC_TRACE_ERROR
+  * 6. ::MQTTASYNC_TRACE_SEVERE
+  * 7. ::MQTTASYNC_TRACE_FATAL
+  *
+  * Selecting ::MQTTASYNC_TRACE_MAXIMUM will cause all trace entries at all levels to be returned. 
+  * Choosing ::MQTTASYNC_TRACE_ERROR will cause ERROR, SEVERE and FATAL trace entries to be returned
+  * to the callback function.
+  *
+  * ### MQTT Packet Tracing
+  * 
+  * A feature that can be very useful is printing the MQTT packets that are sent and received.  To 
+  * achieve this, use the following environment variable settings:
+  * @code
+    MQTT_C_CLIENT_TRACE=ON
+    MQTT_C_CLIENT_TRACE_LEVEL=PROTOCOL
+  * @endcode
+  * The output you should see looks like this:
+  * @code
+    20130528 155936.813 3 stdout-subscriber -> CONNECT cleansession: 1 (0)
+    20130528 155936.813 3 stdout-subscriber <- CONNACK rc: 0
+    20130528 155936.813 3 stdout-subscriber -> SUBSCRIBE msgid: 1 (0)
+    20130528 155936.813 3 stdout-subscriber <- SUBACK msgid: 1
+    20130528 155941.818 3 stdout-subscriber -> DISCONNECT (0)
+  * @endcode
+  * where the fields are:
+  * 1. date
+  * 2. time
+  * 3. socket number
+  * 4. client id
+  * 5. direction (-> from client to server, <- from server to client)
+  * 6. packet details
+  *
+  * ### Default Level Tracing
+  * 
+  * This is an extract of a default level trace of a call to connect:
+  * @code
+    19700101 010000.000 (1152206656) (0)> MQTTClient_connect:893
+    19700101 010000.000 (1152206656)  (1)> MQTTClient_connectURI:716
+    20130528 160447.479 Connecting to serverURI localhost:1883
+    20130528 160447.479 (1152206656)   (2)> MQTTProtocol_connect:98
+    20130528 160447.479 (1152206656)    (3)> MQTTProtocol_addressPort:48
+    20130528 160447.479 (1152206656)    (3)< MQTTProtocol_addressPort:73
+    20130528 160447.479 (1152206656)    (3)> Socket_new:599
+    20130528 160447.479 New socket 4 for localhost, port 1883
+    20130528 160447.479 (1152206656)     (4)> Socket_addSocket:163
+    20130528 160447.479 (1152206656)      (5)> Socket_setnonblocking:73
+    20130528 160447.479 (1152206656)      (5)< Socket_setnonblocking:78 (0)
+    20130528 160447.479 (1152206656)     (4)< Socket_addSocket:176 (0)
+    20130528 160447.479 (1152206656)     (4)> Socket_error:95
+    20130528 160447.479 (1152206656)     (4)< Socket_error:104 (115)
+    20130528 160447.479 Connect pending
+    20130528 160447.479 (1152206656)    (3)< Socket_new:683 (115)
+    20130528 160447.479 (1152206656)   (2)< MQTTProtocol_connect:131 (115)
+  * @endcode
+  * where the fields are:
+  * 1. date
+  * 2. time
+  * 3. thread id
+  * 4. function nesting level
+  * 5. function entry (>) or exit (<)
+  * 6. function name : line of source code file
+  * 7. return value (if there is one)
+  *
+  * ### Memory Allocation Tracing
+  * 
+  * Setting the trace level to maximum causes memory allocations and frees to be traced along with 
+  * the default trace entries, with messages like the following:
+  * @code
+    20130528 161819.657 Allocating 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 177 ptr 0x179f930
+
+    20130528 161819.657 Freeing 16 bytes in heap at file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c line 201, heap use now 896 bytes
+  * @endcode
+  * When the last MQTT client object is destroyed, if the trace is being recorded 
+  * and all memory allocated by the client library has not been freed, an error message will be
+  * written to the trace.  This can help with fixing memory leaks.  The message will look like this:
+  * @code
+    20130528 163909.208 Some memory not freed at shutdown, possible memory leak
+    20130528 163909.208 Heap scan start, total 880 bytes
+    20130528 163909.208 Heap element size 32, line 354, file /home/icraggs/workspaces/mqrtc/mqttv3c/src/MQTTPacket.c, ptr 0x260cb00
+    20130528 163909.208   Content           
+    20130528 163909.209 Heap scan end
+  * @endcode
+  * @endcond
   */
 
 

src/MQTTClient.c

@@ -18,6 +18,12 @@
  *    Ian Craggs - multiple server connection support
  *******************************************************************************/
 
+/**
+ * @file
+ * \brief Synchronous API implementation
+ *
+ */
+
 #include <stdlib.h>
 #if !defined(WIN32)
 	#include <sys/time.h>

src/utf-8.c

@@ -15,32 +15,41 @@
  *******************************************************************************/
 
 
-/*
-  See page 104 of the Unicode Standard 5.0 for the list of well formed
-  UTF-8 byte sequences.
-
-*/
+/**
+ * @file
+ * \brief Functions for checking that strings contain UTF-8 characters only
+ *
+ * See page 104 of the Unicode Standard 5.0 for the list of well formed
+ * UTF-8 byte sequences.
+ * 
+ */
 
 #include <stdlib.h>
 #include <string.h>
 
 #include "StackTrace.h"
 
+/**
+ * Macro to determine the number of elements in a single-dimension array
+ */
 #if !defined(ARRAY_SIZE)
 #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
 #endif
 
 
+/**
+ * Structure to hold the valid ranges of UTF-8 characters, for each byte up to 4
+ */
 struct
 {
-	int len;
+	int len; /**< number of elements in the following array (1 to 4) */
 	struct
 	{
-		char lower;
-		char upper;
-	} bytes[4];
+		char lower; /**< lower limit of valid range */
+		char upper; /**< upper limit of valid range */
+	} bytes[4];   /**< up to 4 bytes can be used per character */
 }
-valid_ranges[] =
+valid_ranges[] = 
 {
 		{1, { {00, 0x7F} } },
 		{2, { {0xC2, 0xDF}, {0x80, 0xBF} } },
@@ -54,6 +63,12 @@ valid_ranges[] =
 };
 
 
+/**
+ * Validate a single UTF-8 character
+ * @param len the length of the string in "data"
+ * @param data the bytes to check for a valid UTF-8 char
+ * @return pointer to the start of the next UTF-8 character in "data"
+ */
 char* UTF8_char_validate(int len, char* data)
 {
 	int good = 0;
@@ -100,6 +115,12 @@ char* UTF8_char_validate(int len, char* data)
 }
 
 
+/**
+ * Validate a length-delimited string has only UTF-8 characters
+ * @param len the length of the string in "data"
+ * @param data the bytes to check for valid UTF-8 characters
+ * @return 1 (true) if the string has only UTF-8 characters, 0 (false) otherwise
+ */
 int UTF8_validate(int len, char* data)
 {
 	char* curdata = NULL;
@@ -116,6 +137,11 @@ int UTF8_validate(int len, char* data)
 }
 
 
+/**
+ * Validate a null-terminated string has only UTF-8 characters
+ * @param string the string to check for valid UTF-8 characters
+ * @return 1 (true) if the string has only UTF-8 characters, 0 (false) otherwise
+ */
 int UTF8_validateString(char* string)
 {
 	int rc = 0;