Fix all Doxygen errors and make any future errors fatal (#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