Documentation change only: nicer Doxygen output. (#609)

Doxyfile

@@ -195,7 +195,7 @@ SHORT_NAMES            = NO
 # description.)
 # The default value is: NO.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line
 # such as
@@ -629,7 +629,7 @@ SORT_MEMBERS_CTORS_1ST = NO
 # appear in their defined order.
 # The default value is: NO.
 
-SORT_GROUP_NAMES       = NO
+SORT_GROUP_NAMES       = YES
 
 # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 # fully-qualified names, including namespaces. If set to NO, the class list will
@@ -823,7 +823,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = 
+INPUT                  =
 
 # 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
@@ -874,7 +874,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = u_mutex_debug.h
+EXCLUDE                = port/platform
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -890,8 +890,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-# Exclude the working directory used by the Jenkinsfile, AgentService and Unity
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */Unity/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -984,7 +983,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = README.md
+USE_MDFILE_AS_MAINPAGE =
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing

README.md

@@ -35,6 +35,8 @@ The key APIs provided by this repo, and their relationships with each other, are
 - The [ubx_protocol](/common/ubx_protocol) API implements the necessary encoding/decoding to talk to u-blox GNSS modules.
 - The [port](/port) API permits all of the above to run on different hosts; this API is not really intended for customer use - you can use it if you wish but it is quite restricted and is intended only to provide what `ubxlib` needs in the form that `ubxlib` needs it.
 
+All APIs are documented with Doxygen compatible comments: simply download the latest [Doxygen](https://doxygen.nl/) and run it from the `ubxlib` directory to obtain the output.
+
 # Supported `ubxlib` host platforms and APIs
 
 Hosts run `ubxlib` and interact with an attached periperal. A host platform contains an MCU, toolchain and RTOS/SDK as listed in the table below. Hosts are typically u-blox open CPU (standalone) modules or other MCUs. To use a host you need a development board or an EVK. Currently `ubxlib` supports the following purchasable boards out-of-the box.
@@ -52,25 +54,25 @@ If your MCU is on the list but your board is not:
 If your MCU is not on the list:
 - To port `ubxlib` to a new host platform follow the [DYI instructions](https://github.com/u-blox/ubxlib_priv/tree/master/port) for the port API.
 
-|`ubxlib` hosts |NINA-W10|NINA-B40 series<br />NINA-B30 series<br />NINA-B1 series<br />ANNA-B1 series<br />|NORA-B1 series|C030 board|PC<sup>*|PC<sup>*|
+|`ubxlib` hosts |NINA-W10|NINA-B40 series<br />NINA-B30 series<br />NINA-B1 series<br />ANNA-B1 series<br />|NORA-B1 series|C030 board|PC<sup>*</sup>|PC<sup>*</sup>|
 |-----------|-----------|--------------|-----|-----|------|------|
 |**MCU**|Espressif ESP32|Nordic nRF52|Nordic nRF53|ST-Micro STM32F4|x86 (win32)|x86 (32-bit Linux)|
 |**Toolchain**|ESP-IDF<br />Arduino-ESP32|GCC<br />nRF Connect|nRF Connect|Cube|MSVC|Zephyr|
 |**RTOS/SDK**|FreeRTOS|FreeRTOS<br />Zephyr|Zephyr|FreeRTOS|Windows|Zephyr|
-|**APIs provided by host only**|[wifi](/wifi)<br />[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")|[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")|[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />| [cell](/cell "cell API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")<br />[location<sup>**](/common/location "location API")<br />[tls&nbsp;security](/common/security "security API")<br>| N/A | N/A |
+|**APIs provided by host only**|[wifi](/wifi)<br />[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")|[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")|[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />| [cell](/cell "cell API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")<br />[location<sup>**</sup>](/common/location "location API")<br />[tls&nbsp;security](/common/security "security API")<br>| N/A | N/A |
 
-<sup>* for development/test purposes
+<sup>*</sup> for development/test purposes.
 
 # Supported modules as `ubxlib` peripherals and APIs
 
 Peripherals are u-blox modules which accept commands (e.g. AT-commands) over a serial interface and have no open MCU environment. To run the APIs they need to be attached to a host which runs `ubxlib`. For example in the [test farm](/port/platform/common/automation/DATABASE.md) combinations of hosts and peripherals are listed.
 
 |`ubxlib` peripherals |NINA-B41 series<br />NINA-B31 series<br />NINA-B1 series<br />ANNA-B1|NINA-W13|NINA-W15|SARA-U2 series|SARA-R4 series<br />SARA-R5 series<br />|SARA-R510M8S<br />SARA-R422M8S|M8 series|
 |-----------|-----------|--------------|-----|-----|------|------|------|
-|**APIs provided by host with peripheral attached**|[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")|[wifi](/wifi)<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")|[wifi](/wifi)<br />[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")|[cell](/cell "cell API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")<br />[location*](/common/location "location API")<br />[tls&nbsp;security](/common/security "security API")<br>|[cell](/cell "cell API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")<br />[location<sup>**](/common/location "location API")<br />[security](/common/security "security API")<br>[mqtt_client](/common/mqtt_client "MQTT client API")|All APIs of<br />SARA-R4,<br />SARA-R5 series&nbsp;+<br />[gnss](/gnss "GNSS API")<br />[location](/common/location "location API")|[gnss](/gnss "GNSS API")<br />[location](/common/location "location API")|
+|**APIs provided by host with peripheral attached**|[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")|[wifi](/wifi)<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")|[wifi](/wifi)<br />[ble](/ble "ble API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")|[cell](/cell "cell API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")<br />[location*](/common/location "location API")<br />[tls&nbsp;security](/common/security "security API")<br>|[cell](/cell "cell API")<br />[device](/common/device "device API")<br />[network](/common/network "network API")<br />[sock](/common/sock "sock API")<br />[location<sup>**</sup>](/common/location "location API")<br />[security](/common/security "security API")<br>[mqtt_client](/common/mqtt_client "MQTT client API")|All APIs of<br />SARA-R4,<br />SARA-R5 series&nbsp;+<br />[gnss](/gnss "GNSS API")<br />[location](/common/location "location API")|[gnss](/gnss "GNSS API")<br />[location](/common/location "location API")|
 
 
-<sup>** Through the u-blox [CellLocate](https://www.u-blox.com/en/product/celllocate) mobile network-based location service.
+<sup>**</sup> Through the u-blox [CellLocate](https://www.u-blox.com/en/product/celllocate) mobile network-based location service.
 
 # Structure of `ubxlib`
 The APIs for each type of u-blox module can be found in the relevant directory (e.g. [cell](/cell) for cellular modules and [ble](/ble)/[wifi](/wifi) for BLE/Wi-Fi modules).  The [common](/common) directory contains APIs and 'helper' modules that are shared by u-blox modules, most importantly the [device](/common/device) API, the [network](/common/network) API and the [sockets](/common/sockets) API.  All APIs are documented in the API header files.

ble/api/u_ble.h

@@ -22,7 +22,11 @@
  * of another module should be included here; otherwise
  * please keep #includes to your .c files. */
 
-/** @file
+/** \addtogroup _BLE _Bluetooth Low Energy
+ *  @{
+ */
+
+ /** @file
  * @brief This header file defines the general ble APIs,
  * basically initialise and deinitialise.
  */
@@ -65,11 +69,11 @@ extern "C" {
 typedef enum {
     U_BLE_ERROR_FORCE_32_BIT = 0x7FFFFFFF,  /**< Force this enum to be 32 bit as it can be
                                                   used as a size also. */
-    U_BLE_ERROR_AT = U_ERROR_BLE_MAX,      /**< -512 if U_ERROR_BASE is 0. */
-    U_BLE_ERROR_NOT_CONFIGURED = U_ERROR_BLE_MAX - 1, /**< -511 if U_ERROR_BASE is 0. */
-    U_BLE_ERROR_NOT_FOUND = U_ERROR_BLE_MAX - 2,  /**< -510 if U_ERROR_BASE is 0. */
-    U_BLE_ERROR_INVALID_MODE = U_ERROR_BLE_MAX - 3,  /**< -509 if U_ERROR_BASE is 0. */
-    U_BLE_ERROR_TEMPORARY_FAILURE = U_ERROR_BLE_MAX - 4  /**< -508 if U_ERROR_BASE is 0. */
+    U_BLE_ERROR_AT = U_ERROR_BLE_MAX,      /**< -512 if #U_ERROR_BASE is 0. */
+    U_BLE_ERROR_NOT_CONFIGURED = U_ERROR_BLE_MAX - 1, /**< -511 if #U_ERROR_BASE is 0. */
+    U_BLE_ERROR_NOT_FOUND = U_ERROR_BLE_MAX - 2,  /**< -510 if #U_ERROR_BASE is 0. */
+    U_BLE_ERROR_INVALID_MODE = U_ERROR_BLE_MAX - 3,  /**< -509 if #U_ERROR_BASE is 0. */
+    U_BLE_ERROR_TEMPORARY_FAILURE = U_ERROR_BLE_MAX - 4  /**< -508 if #U_ERROR_BASE is 0. */
 } uBleErrorCode_t;
 
 /* ----------------------------------------------------------------
@@ -92,6 +96,8 @@ void uBleDeinit(void);
 }
 #endif
 
+/** @}*/
+
 #endif // _U_BLE_H_
 
 // End of file

ble/api/u_ble_cfg.h

@@ -21,10 +21,15 @@
  * dependency between the API of this module and the API
  * of another module should be included here; otherwise
  * please keep #includes to your .c files. */
+
 #include "u_device.h"
 
+/** \addtogroup _BLE
+ *  @{
+ */
+
 /** @file
- * @brief This header file defines the APIs that configure ble.
+ * @brief This header file defines the APIs that configure BLE.
  */
 
 #ifdef __cplusplus
@@ -69,6 +74,8 @@ int32_t uBleCfgConfigure(uDeviceHandle_t devHandle,
 }
 #endif
 
+/** @}*/
+
 #endif // _U_BLE_CFG_H_
 
 // End of file

ble/api/u_ble_module_type.h

@@ -19,6 +19,10 @@
 
 #include "u_short_range_module_type.h"
 
+/** \addtogroup _BLE
+ *  @{
+ */
+
 /** @file
  * @brief This header file defines the module types for ble.
  */
@@ -41,9 +45,9 @@
 /** The possible types of BLE module.
  */
 typedef enum {
-// X macro is used to generate this enum from U_SHORT_RANGE_MODULE_LIST
+// X macro is used to generate this enum from #U_SHORT_RANGE_MODULE_LIST
 // for all entries with field "BLE" set to U_YES.
-// It will prefix the "Module" field from U_SHORT_RANGE_MODULE_LIST with
+// It will prefix the "Module" field from #U_SHORT_RANGE_MODULE_LIST with
 // U_BLE_MODULE_TYPE_, thus creating the enum values below:
 //    U_BLE_MODULE_TYPE_NINA_B1  < Modules NINA-B1. BLE only
 //    U_BLE_MODULE_TYPE_ANNA_B1  < Modules ANNA-B1. BLE only
@@ -62,6 +66,8 @@ typedef enum {
 #undef U_YES
 #undef U_SHORT_RANGE_MODULE
 
+/** @}*/
+
 #endif // _U_BLE_MODULE_TYPE_H_
 
 // End of file