Fix all Doxygen errors and make any future errors fatal (ARMmbed#118)

* Start working on fixing doxygen warnings

* Upgrade doxyfile to Doxygen 1.9.1

* Clean up some unmatched groups and add some exclusions

* Fix docs for rtos::ThisThread not showing up

* Fix up KV store docs

* Fix incorrect @files, some more incorrect groups

* Fix lots of broken links

* Start fixing mbedtls groups

* Fix more mbedtls docs

* Fix remaining mbedtls files with missing or incorrect grouping

* Fix a huge amount of PSA docs errors

* Fix a few more mbedtls docs errors

* Fix __cplusplus not defined for docs, clean up call in callback typedef, fix some docs errors

* Fix some broken doc links in HAL headers

* Fix more PSA doc errors

* Fix some doxygen errors in networking code

* Fix lots of network related doc errors

* Try and fix some CI failures

* Use Doxygen Action instead of doxygen in Mbed container to get the right version

* Try removing docs check

* Add first part of doxygen action

* Add next part of doxygen action

* Fix yaml syntax error

* Add in license check fix

* Try using verbose scancode

* Fix some more docs issues, workaround scancode-toolkit#3179

* Clean up the LoRaRadio get_state() function on each implementation.  Also fix some other compile and doc errors.

* Fix all remaining doxygen errors

* Fix escaping, for realsies this time

* Remove Doxygen unsupported config options, fix some more get_status() declarations

* Fix some UNITTESTS build errors

* Fix one more compile error

* Another unittest error

Author: Jamie Smith

.github/workflows/basic_checks.yml

@@ -26,7 +26,7 @@ jobs:
         name: install dependencies
         shell: bash
         run: |
-          pip install -U scancode-toolkit click gemfileparser
+          pip install -U scancode-toolkit "click>=7,<8"
 
       - 
         name: license check 
@@ -42,6 +42,7 @@ jobs:
             | ( grep -v '^tools/test/toolchains/api_test.py' || true ) \
             | while read file; do cp --parents "${file}" SCANCODE; done
           ls SCANCODE
+          scancode --reindex-licenses # workaround for scancode-toolkit#3179
           scancode -l --json-pp scancode.json SCANCODE
           python ./tools/test/ci/scancode-evaluate.py scancode.json || true
           cat scancode-evaluate.log
@@ -106,21 +107,7 @@ jobs:
             | while read file; do astyle -n --options=.astylerc "${file}"; done
           git diff --exit-code --diff-filter=d --color
 
-
-  docs-check:
-    runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/armmbed/mbed-os-env:master-latest
-
-    steps:
-
-      - name: Checkout repo
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-    
-      - 
-        name: spell checks
+      - name: Spell Checks
         run: |
           set -x
           ./tools/test/ci/doxy-spellchecker/spell.sh drivers .codecheckignore
@@ -129,18 +116,9 @@ jobs:
           ./tools/test/ci/doxy-spellchecker/spell.sh rtos .codecheckignore
           ./tools/test/ci/doxy-spellchecker/spell.sh connectivity/netsocket .codecheckignore
 
-      - 
-        name: doxygen
+      - name: File Naming Checks
         run: |
           set -x
-          ccache -s
-          mkdir BUILD
-          # Assert that the Doxygen build produced no warnings.
-          # The strange command below asserts that the Doxygen command had an
-          # output of zero length
-          doxygen doxyfile_options 2>&1
-          # Once Mbed OS has been fixed, enable the full test by replacing the top line with this:
-          # - ( ! doxygen doxyfile_options 2>&1 | grep . )
           # Assert that all binary libraries are named correctly
           # The strange command below asserts that there are exactly 0 libraries
           # that do not start with lib
@@ -153,6 +131,26 @@ jobs:
           find  -name "*.s" | tee BUILD/badasm |
           sed -e "s/^/Bad Assembler file name found: /" && [ ! -s BUILD/badasm ]
 
+  docs-check:
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: Checkout repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Create BUILD folder
+        run: |
+          mkdir -p ${{ github.workspace }}/BUILD
+
+      - name: Doxygen Action
+        uses: mattnotmitt/[email protected]
+        with:
+          doxyfile-path: ./doxyfile_options
+
   python-tests:
     # these tests run in 3.7, hence running in vm not in pre-built docker
     runs-on: ubuntu-latest

.github/workflows/docs.yaml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         submodules: recursive
 
@@ -21,7 +21,7 @@ jobs:
 
     # Build the HTML documentation
     - name: Doxygen Action
-      uses: mattnotmitt/doxygen-action@v1.1.0
+      uses: mattnotmitt/doxygen-action@v1.9.1
       with:
           doxyfile-path: ./doxyfile_options
 

README.md

@@ -32,13 +32,13 @@ To start a new project that uses Mbed CE, see the setup guide [here](https://git
 
 We have a [developer website](https://os.mbed.com) for asking questions, engaging with others, finding information on boards and components, using an online IDE and compiler, reading the documentation and learning about what's new and what's coming next in Mbed OS.
 
-## Getting started for contributors
-
-We also have a [contributing and publishing guide](https://os.mbed.com/contributing/) that covers licensing, contributor agreements and style guidelines.
+Additionally, the [discussions page](https://github.com/mbed-ce/mbed-os/discussions) on this repo can be used for proposing and discussing specific code changes.
 
 ## Documentation
 
-For more information about Mbed OS, please see [our published documentation](https://os.mbed.com/docs/latest). It includes Doxygen for our APIs, step-by-step tutorials, porting information and background reference materials about our architecture and tools.
+For more information about Mbed OS, please see [our published documentation](https://os.mbed.com/docs/latest). It includes general overview information, step-by-step tutorials, porting information and background reference materials about our architecture and tools.
+
+For the Mbed OS CE class-level documentation, see [here](https://mbed-ce.github.io/mbed-os/group__mbed-os-public.html)
 
 To contribute to this documentation, please see the [mbed-os-5-docs repository](https://github.com/ARMmbed/mbed-os-5-docs).
 

connectivity/FEATURE_BLE/include/ble/driver/CordioHCIDriver.h

@@ -115,6 +115,8 @@ class CordioHCIDriver {
     /**
      * Get the random static address of the controller
      *
+     * @param[out] address MAC address is written here.
+     *
      * @return false if the address has not been set and true otherwise.
      */
     virtual bool get_random_static_address(ble::address_t& address);

connectivity/cellular/include/cellular/framework/API/ATHandler.h

@@ -205,7 +205,7 @@ class ATHandler {
      *        command when you need multiple response parameters to be handled.
      *        NOTE: Does not lock ATHandler for process!
      *
-     * @param cmd AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
+     * @param cmd AT command in form +&lt;CMD&lt; (will be used also in response reading, no extra chars allowed)
      * @param cmd_chr Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
      * @param format Format string for variadic arguments to be added to AT command; No separator needed.
      *        Use %d for integer, %s for string and %b for byte string (requires 2 arguments: string and length)
@@ -214,7 +214,7 @@ class ATHandler {
 
     /**
      * @brief at_cmd_str Send an AT command and read a single string response. Locks and unlocks ATHandler for operation
-     * @param cmd AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
+     * @param cmd AT command in form +&lt;CMD&lt; (will be used also in response reading, no extra chars allowed)
      * @param cmd_chr Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
      * @param resp_buf Response buffer
      * @param resp_buf_size Response buffer size
@@ -226,7 +226,7 @@ class ATHandler {
 
     /**
      * @brief at_cmd_int Send an AT command and read a single integer response. Locks and unlocks ATHandler for operation
-     * @param cmd AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
+     * @param cmd AT command in form +&lt;CMD&lt; (will be used also in response reading, no extra chars allowed)
      * @param cmd_chr Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
      * @param resp Integer to hold response
      * @param format Format string for variadic arguments to be added to AT command; No separator needed.
@@ -237,7 +237,7 @@ class ATHandler {
 
     /**
      * @brief at_cmd_discard Send an AT command and read and discard a response. Locks and unlocks ATHandler for operation
-     * @param cmd AT command in form +<CMD> (will be used also in response reading, no extra chars allowed)
+     * @param cmd AT command in form +&lt;CMD&lt; (will be used also in response reading, no extra chars allowed)
      * @param cmd_chr Char to be added to specific AT command: '?', '=' or ''. Will be used as such so '=1' is valid as well.
      * @param format Format string for variadic arguments to be added to AT command; No separator needed.
      *        Use %d for integer, %s for string and %b for byte string (requires 2 arguments: string and length)

connectivity/cellular/include/cellular/framework/API/CellularContext.h

@@ -36,7 +36,7 @@ namespace mbed {
  * @ingroup mbed-os-public
  * @{
 
- * @defgroup Cellular
+ * @defgroup Cellular Cellular
  * @ingroup connectivity-public-api
  * @{
  */

connectivity/cellular/include/cellular/framework/API/CellularDevice.h

@@ -218,8 +218,7 @@ class CellularDevice {
 
     /** Creates a new CellularContext interface.
      *
-     *  @param fh       file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
-     *                  file handle is used.
+     *
      *  @param apn      access point to use with context, can be null.
      *  @param cp_req       flag indicating if EPS control plane optimization is required
      *  @param nonip_req    flag indicating if this context is required to be Non-IP
@@ -297,17 +296,13 @@ class CellularDevice {
 
     /** Create new CellularNetwork interface.
      *
-     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
-     *               file handle is used.
      *  @return      New instance of interface CellularNetwork.
      */
     virtual CellularNetwork *open_network() = 0;
 
 #if MBED_CONF_CELLULAR_USE_SMS || defined(DOXYGEN_ONLY)
     /** Create new CellularSMS interface.
      *
-     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
-     *               file handle is used.
      *  @return      New instance of interface CellularSMS.
      */
     virtual CellularSMS *open_sms() = 0;
@@ -320,8 +315,6 @@ class CellularDevice {
 
     /** Create new CellularInformation interface.
      *
-     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
-     *               file handle is used.
      *  @return      New instance of interface CellularInformation.
      */
     virtual CellularInformation *open_information() = 0;

connectivity/cellular/include/cellular/framework/AT/AT_CellularDevice.h

@@ -73,7 +73,15 @@ class AT_CellularDevice : public CellularDevice {
     };
 
 public:
-    AT_CellularDevice(FileHandle *fh, char *delim = "\r");
+
+    /**
+     * Create an AT_CellularDevice.
+     *
+     * @param fh    file handle used for reading AT responses and writing AT commands
+     * @param delim delimiter used when parsing at responses, "\r" should be used as output_delimiter
+     */
+    AT_CellularDevice(FileHandle *fh, char const *delim = "\r");
+
     virtual ~AT_CellularDevice();
 
     virtual nsapi_error_t clear();

connectivity/cellular/source/framework/AT/AT_CellularDevice.cpp

@@ -39,7 +39,7 @@ using namespace std::chrono_literals;
 #define DEFAULT_AT_TIMEOUT 1s // at default timeout
 const int MAX_SIM_RESPONSE_LENGTH = 16;
 
-AT_CellularDevice::AT_CellularDevice(FileHandle *fh, char *delim):
+AT_CellularDevice::AT_CellularDevice(FileHandle *fh, char const *delim):
     CellularDevice(),
     _at(fh, _queue, DEFAULT_AT_TIMEOUT, delim),
 #if MBED_CONF_CELLULAR_USE_SMS

connectivity/cellular/tests/UNITTESTS/doubles/AT_CellularDevice_stub.cpp

@@ -33,7 +33,7 @@ bool AT_CellularDevice_stub::pin_needed = false;
 bool AT_CellularDevice_stub::supported_bool = false;
 int AT_CellularDevice_stub::max_sock_value = 1;
 
-AT_CellularDevice::AT_CellularDevice(FileHandle *fh, char *delim) :
+AT_CellularDevice::AT_CellularDevice(FileHandle *fh, char const *delim) :
     CellularDevice(),
     _at(fh, _queue, get_property(AT_CellularDevice::PROPERTY_AT_SEND_DELAY), delim),
 #if MBED_CONF_CELLULAR_USE_SMS

connectivity/drivers/ble/FEATURE_BLE/TARGET_NORDIC/TARGET_NORDIC_CORDIO/TARGET_NRF5x/NRFCordioHCIDriver.h

@@ -48,19 +48,7 @@ class NRFCordioHCIDriver : public CordioHCIDriver {
      */
     virtual void start_reset_sequence();
 
-    /**
-     * Handle HCI messages received during the reset sequence.
-     *
-     * @param msg The HCI message received.
-     * @note The driver should signal to the stack that the initialization
-     * sequence is done by calling the function: signal_reset_sequence_done.
-     */
-    //virtual void handle_reset_sequence(uint8_t *msg);
-
-    /**
-     * @copydoc CordioHCIDriver::get_random_static_address
-     */
-    virtual bool get_random_static_address(ble::address_t& address);
+    bool get_random_static_address(ble::address_t& address) override;
 
 private:
     /**

connectivity/drivers/lora/COMPONENT_SX126X/SX126X_LoRaRadio.cpp

@@ -1269,13 +1269,18 @@ void SX126X_LoRaRadio::set_buffer_base_addr(uint8_t tx_base_addr, uint8_t rx_bas
     write_opmode_command((uint8_t) RADIO_SET_BUFFERBASEADDRESS, buf, 2);
 }
 
-uint8_t SX126X_LoRaRadio::get_status(void)
+radio_state_t SX126X_LoRaRadio::get_status(void)
 {
-    if (_operation_mode != MODE_STDBY_RC || _operation_mode != MODE_SLEEP) {
-        return 0;
+    switch (_operation_mode) {
+        case MODE_TX:
+            return RF_TX_RUNNING;
+        case MODE_RX:
+            return RF_RX_RUNNING;
+        case MODE_CAD:
+            return RF_CAD;
+        default: // various standby states
+            return RF_IDLE;
     }
-
-    return 0xFF;
 }
 
 int8_t SX126X_LoRaRadio::get_rssi()

connectivity/drivers/lora/COMPONENT_SX126X/SX126X_LoRaRadio.h

@@ -89,48 +89,13 @@ class SX126X_LoRaRadio : public LoRaRadio {
      */
     virtual void standby(void);
 
-    /**
-     *  Sets the reception parameters
-     *
-     *  @param modem         Radio modem to be used [0: FSK, 1: LoRa]
-     *  @param bandwidth     Sets the bandwidth
-     *                          FSK : >= 2600 and <= 250000 Hz
-     *                          LoRa: [0: 125 kHz, 1: 250 kHz,
-     *                                 2: 500 kHz, 3: Reserved]
-     *  @param datarate      Sets the Datarate
-     *                          FSK : 600..300000 bits/s
-     *                          LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
-     *                                10: 1024, 11: 2048, 12: 4096  chips]
-     *  @param coderate      Sets the coding rate ( LoRa only )
-     *                          FSK : N/A ( set to 0 )
-     *                          LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
-     *  @param bandwidth_afc Sets the AFC Bandwidth ( FSK only )
-     *                          FSK : >= 2600 and <= 250000 Hz
-     *                          LoRa: N/A ( set to 0 )
-     *  @param preamble_len  Sets the Preamble length ( LoRa only )
-     *                          FSK : N/A ( set to 0 )
-     *                          LoRa: Length in symbols ( the hardware adds 4 more symbols )
-     *  @param symb_timeout  Sets the RxSingle timeout value
-     *                          FSK : timeout number of bytes
-     *                          LoRa: timeout in symbols
-     *  @param fixLen        Fixed length packets [0: variable, 1: fixed]
-     *  @param payload_len   Sets payload length when fixed lenght is used
-     *  @param crc_on        Enables/Disables the CRC [0: OFF, 1: ON]
-     *  @param freq_hop_on   Enables disables the intra-packet frequency hopping  [0: OFF, 1: ON] (LoRa only)
-     *  @param hop_period    Number of symbols bewteen each hop (LoRa only)
-     *  @param iq_inverted   Inverts IQ signals ( LoRa only )
-     *                          FSK : N/A ( set to 0 )
-     *                          LoRa: [0: not inverted, 1: inverted]
-     *  @param rx_continuous Sets the reception in continuous mode
-     *                          [false: single mode, true: continuous mode]
-     */
-    virtual void set_rx_config(radio_modems_t modem, uint32_t bandwidth,
-                               uint32_t datarate, uint8_t coderate,
-                               uint32_t bandwidth_afc, uint16_t preamble_len,
-                               uint16_t symb_timeout, bool fix_len,
-                               uint8_t payload_len,
-                               bool crc_on, bool freq_hop_on, uint8_t hop_period,
-                               bool iq_inverted, bool rx_continuous);
+    void set_rx_config(radio_modems_t modem, uint32_t bandwidth,
+                       uint32_t datarate, uint8_t coderate,
+                       uint32_t bandwidth_afc, uint16_t preamble_len,
+                       uint16_t symb_timeout, bool fix_len,
+                       uint8_t payload_len,
+                       bool crc_on, bool freq_hop_on, uint8_t hop_period,
+                       bool iq_inverted, bool rx_continuous) override;
 
     /**
      *  Sets the transmission parameters
@@ -204,13 +169,7 @@ class SX126X_LoRaRadio : public LoRaRadio {
      */
     virtual uint32_t random(void);
 
-    /**
-     *  Get radio status
-     *
-     *  @param status        Radio status [RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING]
-     *  @return              Return current radio status
-     */
-    virtual uint8_t get_status(void);
+    radio_state_t get_status(void) override;
 
     /**
      *  Sets the maximum payload length

connectivity/drivers/lora/COMPONENT_SX126X/sx126x_ds.h

@@ -1,9 +1,9 @@
 /*!
- * \file      sx126x.h
+ * \file      sx126x_ds.h
  *
  * \brief     SX126x driver implementation
  *
- * \copyright Revised BSD License, see section \ref LICENSE.
+ * \copyright Revised BSD License
  *
  * \code
  *                ______                              _