some Doxygen improvements

Doxyfile

@@ -2037,7 +2037,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = "__DOXYGEN="
 
 # 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. The

include/mqtt.h

@@ -111,12 +111,12 @@ extern "C" {
  * @defgroup unpackers Control Packet Deserialization
  * @brief Developer documentation of the functions and datastructures used for deserializing MQTT 
  *        control packets.
- * 
- * @defgroup details Utilities
- * @brief Developer documentation for the utilities used to implement the MQTT-C client.
  *
  * @note To deserialize a packet from a buffer use \ref mqtt_unpack_response (it's the only 
  *       function you need).
+ * 
+ * @defgroup details Utilities
+ * @brief Developer documentation for the utilities used to implement the MQTT-C client.
  */
 
 
@@ -330,6 +330,7 @@ struct mqtt_response_connack {
 
  /**
   * @brief A publish packet received from the broker.
+  * @ingroup api
   * @ingroup unpackers
   * 
   * A publish packet is received from the broker when a client publishes to a topic that the 
@@ -666,7 +667,7 @@ ssize_t mqtt_pack_fixed_header(uint8_t *buf, size_t bufsz, const struct mqtt_fix
 
 /**
  * @brief An enumeration of CONNECT packet flags.
- * @ingroup packers
+ * @ingroup api
  * 
  * @see <a href="http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718030">
  * MQTT v3.1.1: CONNECT Variable Header.
@@ -734,7 +735,7 @@ ssize_t mqtt_pack_connection_request(uint8_t* buf, size_t bufsz,
 
 /**
  * @brief An enumeration of the PUBLISH flags.
- * @ingroup packers
+ * @ingroup api
  * 
  * @see <a href="http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718037">
  * MQTT v3.1.1: PUBLISH - Publish Message.
@@ -1087,6 +1088,7 @@ struct mqtt_queued_message* mqtt_mq_find(const struct mqtt_message_queue *mq, en
 
 /**
  * @brief An MQTT client. 
+ * @ingroup api
  * @ingroup details
  * 
  * @note All members can be manipulated via the related functions.
@@ -1606,7 +1608,7 @@ enum MQTTErrors mqtt_disconnect(struct mqtt_client *client);
  * @ingroup api
  * 
  * @note The user must provide a reconnect callback function for this to 
- * work as expected. See \r mqtt_client_reconnect.
+ * work as expected. See \ref mqtt_reconnect.
  * 
  * @pre mqtt_connect must have been called
 * 

include/mqtt_pal.h

@@ -46,30 +46,78 @@ extern "C" {
  *      - \c size_t, \c ssize_t
  *      - \c uint8_t, \c uint16_t, \c uint32_t
  *      - \c va_list
- *      - \c mqtt_pal_time_t : return type of \c MQTT_PAL_TIME() 
- *      - \c mqtt_pal_mutex_t : type of the argument that is passed to \c MQTT_PAL_MUTEX_LOCK and 
- *        \c MQTT_PAL_MUTEX_RELEASE
+ *      - \ref mqtt_pal_time_t
+ *      - \ref mqtt_pal_mutex_t
  *  - Functions:
  *      - \c memcpy, \c strlen
  *      - \c va_start, \c va_arg, \c va_end
  *  - Constants:
  *      - \c INT_MIN
  * 
- * Additionally, three macro's are required:
- *  - \c MQTT_PAL_HTONS(s) : host-to-network endian conversion for uint16_t.
- *  - \c MQTT_PAL_NTOHS(s) : network-to-host endian conversion for uint16_t.
- *  - \c MQTT_PAL_TIME()   : returns [type: \c mqtt_pal_time_t] current time in seconds. 
- *  - \c MQTT_PAL_MUTEX_LOCK(mtx_pointer) : macro that locks the mutex pointed to by \c mtx_pointer.
- *  - \c MQTT_PAL_MUTEX_RELEASE(mtx_pointer) : macro that unlocks the mutex pointed to by 
- *    \c mtx_pointer.
+ * Additionally, six macro's are required:
+ *  - \c MQTT_PAL_HTONS(s)
+ *  - \c MQTT_PAL_NTOHS(s)
+ *  - \c MQTT_PAL_TIME()
+ *  - \c MQTT_PAL_MUTEX_INIT(mtx_ptr)
+ *  - \c MQTT_PAL_MUTEX_LOCK(mtx_ptr)
+ *  - \c MQTT_PAL_MUTEX_UNLOCK(mtx_ptr)
  * 
  * Lastly, \ref mqtt_pal_sendall and \ref mqtt_pal_recvall, must be implemented in mqtt_pal.c 
  * for sending and receiving data using the platforms socket calls.
  */
 
+#if defined(__DOXYGEN)
+/**
+ * @brief host-to-network endian conversion for uint16_t.
+ * @ingroup pal
+ */
+    #define MQTT_PAL_HTONS(s)
+
+/**
+ * @brief network-to-host endian conversion for uint16_t.
+ * @ingroup pal
+ */
+    #define MQTT_PAL_NTOHS(s)
+
+/**
+ * @brief returns [type: \c mqtt_pal_time_t] current time in seconds.
+ * @ingroup pal
+ */
+    #define MQTT_PAL_TIME()
+
+/**
+ * @brief macro that initializes the mutex pointed to by \c mtx_ptr.
+ * @ingroup pal
+ */
+    #define MQTT_PAL_MUTEX_INIT(mtx_ptr)
+
+/**
+ * @brief macro that locks the mutex pointed to by \c mtx_ptr.
+ * @ingroup pal
+ */
+    #define MQTT_PAL_MUTEX_LOCK(mtx_ptr)
+
+/**
+ * @brief macro that unlocks the mutex pointed to by \c mtx_ptr.
+ * @ingroup pal
+ */
+    #define MQTT_PAL_MUTEX_UNLOCK(mtx_ptr)
+
+/**
+ * @brief return type of \c MQTT_PAL_TIME()
+ * @ingroup pal
+ */
+    typedef void mqtt_pal_time_t;
+
+/**
+ * @brief type of the argument that is passed to \c MQTT_PAL_MUTEX_INIT(),
+ * \c MQTT_PAL_MUTEX_LOCK() and \c MQTT_PAL_MUTEX_UNLOCK().
+ * @ingroup pal
+ */
+    typedef void mqtt_pal_mutex_t;
 
-/* UNIX-like platform support */
-#if defined(__unix__) || defined(__APPLE__) || defined(__NuttX__)
+#elif defined(__unix__) || defined(__APPLE__) || defined(__NuttX__)
+    /* UNIX-like platform support */
     #include <limits.h>
     #include <string.h>
     #include <stdarg.h>