Merge pull request #4508 from kegilbert/kg-doxygen-framework-hal-rtos

Doxygen combined HAL, RTOS, and features/Framework updates to not produce warnings and errors [DOC Changes Only]

Author: sg-

doxyfile_options

@@ -840,14 +840,12 @@ EXCLUDE_PATTERNS       = */tools/* \
                          */TESTS/* \
                          */targets/* \
                          */BUILD/* \
-                         */rtos/* \
+                         */rtos/rtx* \
                          */cmsis/* \
-                         */hal/* \
                          */FEATURE_* \
                          */features/mbedtls/* \
                          */features/storage/* \
                          */features/unsupported/* \
-                         */features/frameworks/* \
                          */features/filesystem/* \
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names

doxygen_options.json

@@ -8,5 +8,5 @@
     "PREDEFINED": "DOXYGEN_ONLY \"MBED_DEPRECATED_SINCE(f, g)=\" \"MBED_ENABLE_IF_CALLBACK_COMPATIBLE(F, M)=\"",
     "EXPAND_AS_DEFINED": "", 
     "SKIP_FUNCTION_MACROS": "NO",
-    "EXCLUDE_PATTERNS": "*/tools/* */TESTS/* */targets/* */FEATURE_*/* */features/mbedtls/* */features/storage/* */features/unsupported/* */features/frameworks/* */features/filesystem/* */BUILD/* */rtos/* */cmsis/* */hal/* */features/FEATURES_*"
+    "EXCLUDE_PATTERNS": "*/tools/* */TESTS/* */targets/* */FEATURE_*/* */features/mbedtls/* */features/storage/* */features/unsupported/* */features/filesystem/* */BUILD/* */rtos/rtx*/* */cmsis/* */features/FEATURES_*"
 }

features/frameworks/utest/utest/utest_case.h

@@ -36,7 +36,7 @@ namespace v1 {
      *
      * @warning Initialization of handlers with either default_handler or 
      * ignore_handler helpers will prevent the object to be a POD. Prefer usage 
-     * of NULL in favor of ignore_handler or <handler_type>(1) for default 
+     * of NULL in favor of ignore_handler or \verbatim <handler_type>(1) \endverbatim for default 
      * handler.
      *
      * @see Case.

features/frameworks/utest/utest/utest_default_handlers.h

@@ -38,13 +38,17 @@ namespace v1 {
      */
     static const struct
     {
+        ///@cond IGNORE
+        // Doxygen can't parse these implicit conversion operators properly, remove from
+        // doc build
         operator test_setup_handler_t()    const { return test_setup_handler_t(1); }
         operator test_teardown_handler_t() const { return test_teardown_handler_t(1); }
         operator test_failure_handler_t()  const { return test_failure_handler_t(1); }
 
         operator case_setup_handler_t()    const { return case_setup_handler_t(1); }
         operator case_teardown_handler_t() const { return case_teardown_handler_t(1); }
         operator case_failure_handler_t()  const { return case_failure_handler_t(1); }
+        ///@endcond
     } default_handler;
 
     /** Ignore handler hint.
@@ -55,6 +59,9 @@ namespace v1 {
      */
     static const struct
     {
+        ///@cond IGNORE
+        // Doxygen can't parse these implicit conversion operators properly, remove from
+        // doc build
         operator case_handler_t()            const { return case_handler_t(NULL); }
         operator case_control_handler_t()    const { return case_control_handler_t(NULL); }
         operator case_call_count_handler_t() const { return case_call_count_handler_t(NULL); }
@@ -66,6 +73,7 @@ namespace v1 {
         operator case_setup_handler_t()    const { return case_setup_handler_t(NULL); }
         operator case_teardown_handler_t() const { return case_teardown_handler_t(NULL); }
         operator case_failure_handler_t()  const { return case_failure_handler_t(NULL); }
+        ///@endcond
     } ignore_handler;
 
     /** A table of handlers.

features/frameworks/utest/utest/utest_types.h

@@ -30,6 +30,7 @@ namespace utest {
 /** @{*/
 namespace v1 {
 
+    /// repeat_t
     enum repeat_t {
         REPEAT_UNDECLR = 0,
         REPEAT_NONE    = 1,       ///< continue with the next test case
@@ -47,12 +48,14 @@ namespace v1 {
         REPEAT_HANDLER = REPEAT_CASE_ONLY | REPEAT_ON_VALIDATE              ///< repeat only the handler
     };
 
+    /// status_t
     enum status_t {
         STATUS_CONTINUE = -1,   ///< continues testing
         STATUS_IGNORE = -2,     ///< ignores failure and continues testing
         STATUS_ABORT = -3       ///< stops testing
     };
 
+    /// failure_reason_t
     enum failure_reason_t {
         REASON_NONE          = 0,           ///< No failure occurred
 
@@ -74,6 +77,7 @@ namespace v1 {
         REASON_IGNORE        = 0x8000       ///< The failure may be ignored
     };
 
+    /// location_t
     enum location_t {
         LOCATION_NONE = 0,      ///< No location information
         LOCATION_TEST_SETUP,    ///< A failure occurred in the test setup

hal/gpio_api.h

@@ -83,38 +83,38 @@ int gpio_read(gpio_t *obj);
 
 /** Init the input pin and set mode to PullDefault
  *
- * @param obj The GPIO object
- * @param pin The pin name
+ * @param gpio The GPIO object
+ * @param pin  The pin name
  */
 void gpio_init_in(gpio_t* gpio, PinName pin);
 
 /** Init the input pin and set the mode
  *
- * @param obj  The GPIO object
- * @param pin  The pin name
- * @param mode The pin mode to be set
+ * @param gpio  The GPIO object
+ * @param pin   The pin name
+ * @param mode  The pin mode to be set
  */
 void gpio_init_in_ex(gpio_t* gpio, PinName pin, PinMode mode);
 
 /** Init the output pin as an output, with predefined output value 0
  *
- * @param obj The GPIO object
- * @param pin The pin name
- * @return An integer value 1 or 0
+ * @param gpio The GPIO object
+ * @param pin  The pin name
+ * @return     An integer value 1 or 0
  */
 void gpio_init_out(gpio_t* gpio, PinName pin);
 
 /** Init the pin as an output and set the output value
  *
- * @param obj   The GPIO object
+ * @param gpio  The GPIO object
  * @param pin   The pin name
  * @param value The value to be set
  */
 void gpio_init_out_ex(gpio_t* gpio, PinName pin, int value);
 
 /** Init the pin to be in/out
  *
- * @param obj       The GPIO object
+ * @param gpio      The GPIO object
  * @param pin       The pin name
  * @param direction The pin direction to be set
  * @param mode      The pin mode to be set

hal/storage_abstraction/Driver_Storage.h

@@ -615,9 +615,9 @@ typedef struct _ARM_DRIVER_STORAGE {
    *
    * This optional function erases the complete device. If the device does not
    *    support global erase then the function returns the error value \ref
-   *    ARM_DRIVER_ERROR_UNSUPPORTED. The data field \em 'erase_all' =
-   *    \token{1} of the structure \ref ARM_STORAGE_CAPABILITIES encodes that
-   *    \ref ARM_STORAGE_EraseAll is supported.
+   *    ARM_DRIVER_ERROR_UNSUPPORTED. The data field \em 'erase_all' = 1
+   *    of the structure \ref ARM_STORAGE_CAPABILITIES encodes that
+   *    ARM_STORAGE_EraseAll is supported.
    *
    * @note This API may execute asynchronously if
    *     ARM_STORAGE_CAPABILITIES::asynchronous_ops is set. Asynchronous

hal/ticker_api.h

@@ -163,7 +163,8 @@ us_timestamp_t ticker_read_us(const ticker_data_t *const ticker);
 
 /** Read the next event's timestamp
  *
- * @param ticker The ticker object.
+ * @param ticker        The ticker object.
+ * @param timestamp     The timestamp object.
  * @return 1 if timestamp is pending event, 0 if there's no event pending
  */
 int ticker_get_next_timestamp(const ticker_data_t *const ticker, timestamp_t *timestamp);

rtos/MemoryPool.h

@@ -76,8 +76,8 @@ class MemoryPool {
     }
 
     /** Free a memory block.
-      @param   address of the allocated memory block to be freed.
-      @return  status code that indicates the execution status of the function.
+      @param   block  address of the allocated memory block to be freed.
+      @return         status code that indicates the execution status of the function.
     */
     osStatus free(T *block) {
         return osMemoryPoolFree(_id, (void*)block);

rtos/Semaphore.h

@@ -40,7 +40,7 @@ namespace rtos {
 class Semaphore {
 public:
     /** Create and Initialize a Semaphore object used for managing resources.
-      @param number of available resources; maximum index value is (count-1). (default: 0).
+      @param count      number of available resources; maximum index value is (count-1). (default: 0).
     */
     Semaphore(int32_t count=0);
 

rtos/Thread.h

@@ -85,7 +85,6 @@ class Thread {
 
     /** Create a new thread, and start it executing the specified function.
       @param   task           function to be executed by this thread.
-      @param   argument       pointer that is passed to the thread function as start argument. (default: NULL).
       @param   priority       initial priority of the thread function. (default: osPriorityNormal).
       @param   stack_size     stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
       @param   stack_mem      pointer to the stack area to be used by this thread (default: NULL).
@@ -112,9 +111,8 @@ class Thread {
     }
 
     /** Create a new thread, and start it executing the specified function.
-      @param   obj            argument to task.
-      @param   method         function to be executed by this thread.
       @param   argument       pointer that is passed to the thread function as start argument. (default: NULL).
+      @param   task           argument to task.
       @param   priority       initial priority of the thread function. (default: osPriorityNormal).
       @param   stack_size     stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
       @param   stack_mem      pointer to the stack area to be used by this thread (default: NULL).
@@ -143,9 +141,8 @@ class Thread {
     }
 
     /** Create a new thread, and start it executing the specified function.
-      @param   obj            argument to task.
-      @param   method         function to be executed by this thread.
       @param   argument       pointer that is passed to the thread function as start argument. (default: NULL).
+      @param   task           argument to task.
       @param   priority       initial priority of the thread function. (default: osPriorityNormal).
       @param   stack_size     stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
       @param   stack_mem      pointer to the stack area to be used by this thread (default: NULL).