Harmonise Doxygen comments in drivers, events, platform and rtos dirs

When a Doxygen group has been defined (created), all its needed to add documentation to that group is `\addtogroup`. Since all the information about the group is preserved, it is not necessary to mention the group hierarchy again with `\ingroup`. This PR removes unnecessary Doxygen lines across the `drivers`, `events`, `platform` and `rtos` directories. It also ensures that new groups are created with `\defgroup` once and referenced with `\addtogroup` whenever documentation needs to be added to an existing group.
create-msugi · Sep 9, 2019 · 5933dec · 5933dec
1 parent d8c2c6f
commit 5933dec
Show file tree

Hide file tree

Showing 76 changed files with 176 additions and 211 deletions.
diff --git a/drivers/AnalogIn.h b/drivers/AnalogIn.h
@@ -28,7 +28,7 @@
 namespace mbed {
 /** \defgroup mbed-os-public Public API */
 
-/** \addtogroup drivers-public-api Drivers
+/** \defgroup drivers-public-api Drivers
  * \ingroup mbed-os-public
  */
 

diff --git a/drivers/AnalogOut.h b/drivers/AnalogOut.h
@@ -25,8 +25,6 @@
 #include "platform/PlatformMutex.h"
 
 namespace mbed {
-/** \addtogroup drivers-public-api */
-
 /**
  * \defgroup drivers_AnalogOut AnalogOut class
  * \ingroup drivers-public-api-gpio

diff --git a/drivers/Ethernet.h b/drivers/Ethernet.h
@@ -23,9 +23,10 @@
 #if DEVICE_ETHERNET || defined(DOXYGEN_ONLY)
 
 namespace mbed {
-/** \ingroup mbed-os-public */
+
 /** \addtogroup drivers-public-api */
 /** @{*/
+
 /**
  * \defgroup drivers_Ethernet Ethernet class
  * @{

diff --git a/drivers/FlashIAP.h b/drivers/FlashIAP.h
@@ -49,9 +49,9 @@ extern uint32_t Load$$LR$$LR_IROM1$$Limit[];
 
 namespace mbed {
 
-/** \ingroup mbed-os-public */
 /** \addtogroup drivers-public-api */
 /** @{*/
+
 /**
  * \defgroup drivers_FlashIAP FlashIAP class
  * @{

diff --git a/drivers/I2CSlave.h b/drivers/I2CSlave.h
@@ -25,7 +25,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_I2CSlave I2CSlave class
+ * \defgroup drivers_I2CSlave I2CSlave class
  * \ingroup drivers-public-api-i2c
  * @{
  */

diff --git a/drivers/LowPowerTimeout.h b/drivers/LowPowerTimeout.h
@@ -27,7 +27,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_LowPowerTimeout LowPowerTimeout class
+ * \defgroup drivers_LowPowerTimeout LowPowerTimeout class
  * \ingroup drivers-public-api-ticker
  * @{
  */

diff --git a/drivers/LowPowerTimer.h b/drivers/LowPowerTimer.h
@@ -27,7 +27,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_LowPowerTimer LowPowerTimer class
+ * \defgroup drivers_LowPowerTimer LowPowerTimer class
  * \ingroup drivers-public-api-ticker
  * @{
  */

diff --git a/drivers/MbedCRC.h b/drivers/MbedCRC.h
@@ -40,7 +40,6 @@ but we check for ( width < 8) before performing shift, so it should not be an is
 #endif
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup drivers-public-api */
 /** @{*/
 /**

diff --git a/drivers/ResetReason.h b/drivers/ResetReason.h
@@ -22,9 +22,9 @@
 #include "reset_reason_api.h"
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup drivers-public-api */
 /** @{*/
+
 /**
  * \defgroup drivers_ResetReason ResetReason class
  * @{

diff --git a/drivers/SPI.h b/drivers/SPI.h
@@ -46,7 +46,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_SPI SPI class
+ * \defgroup drivers_SPI SPI class
  * \ingroup drivers-public-api-spi
  * @{
  */

diff --git a/drivers/Ticker.h b/drivers/Ticker.h
@@ -26,7 +26,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_Ticker Ticker class
+ * \defgroup drivers_Ticker Ticker class
  * \ingroup drivers-public-api-ticker
  * @{
  */

diff --git a/drivers/Timeout.h b/drivers/Timeout.h
@@ -22,7 +22,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_Timeout Timeout class
+ * \defgroup drivers_Timeout Timeout class
  * \ingroup drivers-public-api-ticker
  * @{
  */

diff --git a/drivers/Timer.h b/drivers/Timer.h
@@ -23,7 +23,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_Timer Timer class
+ * \defgroup drivers_Timer Timer class
  * \ingroup drivers-public-api-ticker
  * @{
  */

diff --git a/drivers/TimerEvent.h b/drivers/TimerEvent.h
@@ -22,7 +22,7 @@
 
 namespace mbed {
 /**
- * \addtogroup drivers_TimerEvent TimerEvent class
+ * \defgroup drivers_TimerEvent TimerEvent class
  * \ingroup drivers-public-api-ticker
  * @{
  */

diff --git a/drivers/internal/MIDIMessage.h b/drivers/internal/MIDIMessage.h
@@ -43,7 +43,7 @@
 
 /**
  * \defgroup drivers_MIDIMessage MIDIMessage class
- * \ingroup drivers-internal-usb
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 

diff --git a/drivers/internal/TableCRC.h b/drivers/internal/TableCRC.h
@@ -22,7 +22,6 @@
 
 namespace mbed {
 /** \addtogroup drivers-internal-api
- * \ingroup mbed-os-internal
  * @{
  */
 

diff --git a/events/Event.h b/events/Event.h
@@ -21,8 +21,7 @@
 #include "platform/mbed_assert.h"
 
 namespace events {
-/**
- * \addtogroup events-public-api Events
+/** \defgroup events-public-api Events
  * \ingroup mbed-os-public
  * @{
  */

diff --git a/events/UserAllocatedEvent.h b/events/UserAllocatedEvent.h
@@ -23,8 +23,7 @@
 
 namespace events {
 /**
- * \addtogroup events-public-api Events
- * \ingroup mbed-os-public
+ * \addtogroup events-public-api
  * @{
  */
 template <typename F, typename A>

diff --git a/events/mbed_shared_queues.h b/events/mbed_shared_queues.h
@@ -19,7 +19,6 @@
 #include "events/EventQueue.h"
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup events-public-api */
 /** @{*/
 

diff --git a/platform/ATCmdParser.h b/platform/ATCmdParser.h
@@ -27,8 +27,6 @@
 #include "platform/FileHandle.h"
 
 namespace mbed {
-
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api Platform */
 /** @{*/
 /**

diff --git a/platform/CThunk.h b/platform/CThunk.h
@@ -1,18 +1,4 @@
-/** \ingroup mbed-os-public */
-/** \addtogroup platform-public-api */
-/** @{*/
-/**
- * \defgroup platform_CThunk CThunk class
- * @{
- */
-/* General C++ Object Thunking class
- *
- * - allows direct callbacks to non-static C++ class functions
- * - keeps track for the corresponding class instance
- * - supports an optional context parameter for the called function
- * - ideally suited for class object receiving interrupts (NVIC_SetVector)
- *
- * Copyright (c) 2014-2019 ARM Limited
+/* Copyright (c) 2014-2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -28,6 +14,15 @@
  * limitations under the License.
  */
 
+
+/** \addtogroup platform-public-api */
+/** @{*/
+
+/**
+ * \defgroup platform_CThunk CThunk class
+ * @{
+ */
+
 /* General C++ Object Thunking class
  *
  * - allows direct callbacks to non-static C++ class functions

diff --git a/platform/Callback.h b/platform/Callback.h
@@ -24,7 +24,6 @@
 #include "platform/mbed_toolchain.h"
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

diff --git a/platform/CircularBuffer.h b/platform/CircularBuffer.h
@@ -51,7 +51,6 @@ struct is_unsigned<unsigned long long> {
 };
 };
 
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

diff --git a/platform/CriticalSectionLock.h b/platform/CriticalSectionLock.h
@@ -21,8 +21,6 @@
 #include "platform/mbed_toolchain.h"
 
 namespace mbed {
-
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

diff --git a/platform/DeepSleepLock.h b/platform/DeepSleepLock.h
@@ -21,8 +21,6 @@
 #include <stdint.h>
 
 namespace mbed {
-
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

diff --git a/platform/DirHandle.h b/platform/DirHandle.h
@@ -22,7 +22,6 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

diff --git a/platform/FunctionPointer.h b/platform/FunctionPointer.h
@@ -23,7 +23,6 @@
 #include <stdint.h>
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

diff --git a/platform/LocalFileSystem.h b/platform/LocalFileSystem.h
@@ -26,7 +26,6 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

diff --git a/platform/NonCopyable.h b/platform/NonCopyable.h
@@ -24,9 +24,9 @@
 
 namespace mbed {
 
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
+
 /**
  * \defgroup platform_NonCopyable NonCopyable class
  * @{

diff --git a/platform/PlatformMutex.h b/platform/PlatformMutex.h
@@ -19,7 +19,6 @@
 
 #include "platform/NonCopyable.h"
 
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 

diff --git a/platform/ScopedLock.h b/platform/ScopedLock.h
@@ -21,9 +21,9 @@
 
 namespace mbed {
 
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
+
 /**
  * \defgroup platform_ScopedLock ScopedLock functions
  * @{

diff --git a/platform/ScopedRamExecutionLock.h b/platform/ScopedRamExecutionLock.h
@@ -21,7 +21,6 @@
 
 namespace mbed {
 
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 

diff --git a/platform/ScopedRomWriteLock.h b/platform/ScopedRomWriteLock.h
@@ -21,7 +21,6 @@
 
 namespace mbed {
 
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 

diff --git a/platform/SingletonPtr.h b/platform/SingletonPtr.h
@@ -1,11 +1,3 @@
-
-/** \ingroup mbed-os-public */
-/** \addtogroup platform-public-api */
-/** @{*/
-/**
- * \defgroup platform_SingletonPtr SingletonPtr class
- * @{
- */
 /* mbed Microcontroller Library
  * Copyright (c) 2006-2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
@@ -38,6 +30,14 @@
 extern osMutexId_t singleton_mutex_id;
 #endif
 
+/** \addtogroup platform-public-api */
+/** @{*/
+
+/**
+ * \defgroup platform_SingletonPtr SingletonPtr class
+ * @{
+ */
+
 /** Lock the singleton mutex
  *
  * This function is typically used to provide

diff --git a/platform/Span.h b/platform/Span.h
@@ -26,9 +26,9 @@
 
 namespace mbed {
 
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
+
 /**
  * \defgroup platform_Span Span class
  * @{

diff --git a/platform/Stream.h b/platform/Stream.h
@@ -25,9 +25,9 @@
 #include <cstdarg>
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
+
 /**
  * \defgroup platform_Stream Stream class
  * @{

diff --git a/platform/Transaction.h b/platform/Transaction.h
@@ -20,9 +20,9 @@
 #include "platform/platform.h"
 
 namespace mbed {
-/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
+
 /**
  * \defgroup platform_Transaction Transaction class
  * @{

diff --git a/platform/internal/CThunkBase.h b/platform/internal/CThunkBase.h
@@ -18,7 +18,7 @@
 #ifndef __CTHUNK_BASE_H__
 #define __CTHUNK_BASE_H__
 
-/** \addtogroup platform-internal-api Platform
+/** \defgroup platform-internal-api Platform
  * \ingroup mbed-os-internal
  */
-Original file line number
+Diff line change
@@ Expand Up / @@ -43,7 +43,7 @@ @@
     /**
      * \defgroup drivers_MIDIMessage MIDIMessage class
-     * \ingroup drivers-internal-usb
+     * \ingroup drivers-internal-api-usb
      * @{
      */
@@ Expand Down @@