Change Doxygen groups structure, splitting first by Public/Internal (#11105)

* Change Doxygen groups structure, splitting first by Public/Internal

This commit also does the following:
* groups the documentation of related API
* moves `events/internal/equeue.h` to `events/equeue.h`
* merges `events/source/README.md` to `events/README.md`

UNITTESTS/target_h/drivers/LowPowerTicker.h

@@ -21,7 +21,6 @@
 #include "Callback.h"
 
 namespace mbed {
-/** \addtogroup drivers */
 
 /** mock Low Power Ticker
  *

drivers/AnalogIn.h

@@ -26,11 +26,19 @@
 #include "platform/PlatformMutex.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api Public API */
-/** @{*/
+/** \defgroup mbed-os-public Public API */
+
+/** \addtogroup drivers-public-api Drivers
+ * \ingroup mbed-os-public
+ */
+
+/** \defgroup drivers-public-api-gpio GPIO
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_AnalogIn AnalogIn class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -120,7 +128,6 @@ protected:
 
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/AnalogOut.h

@@ -25,11 +25,11 @@
 #include "platform/PlatformMutex.h"
 
 namespace mbed {
-/** \ingroup drivers */
 /** \addtogroup drivers-public-api */
-/** @{*/
+
 /**
  * \defgroup drivers_AnalogOut AnalogOut class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -147,7 +147,6 @@ protected:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/BusIn.h

@@ -23,11 +23,13 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
+/** \defgroup drivers-public-api-bus Bus
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_BusIn BusIn class
+ * \ingroup drivers-public-api-bus
  * @{
  */
 
@@ -130,7 +132,6 @@ private:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/BusInOut.h

@@ -22,11 +22,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_BusInOut BusInOut class
+ * \ingroup drivers-public-api-bus
  * @{
  */
 
@@ -152,7 +150,6 @@ protected:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/BusOut.h

@@ -22,11 +22,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_BusOut BusOut class
+ * \ingroup drivers-public-api-bus
  * @{
  */
 
@@ -130,7 +128,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/CAN.h

@@ -27,11 +27,13 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
+/** \defgroup drivers-public-api-can CAN
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_CANMessage CANMessage class
+ * \ingroup drivers-public-api-can
  * @{
  */
 
@@ -107,6 +109,7 @@ public:
 
 /**
  * \defgroup drivers_CAN CAN class
+ * \ingroup drivers-public-api-can
  * @{
  */
 
@@ -333,7 +336,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/DigitalIn.h

@@ -22,11 +22,9 @@
 #include "hal/gpio_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_DigitalIn DigitalIn class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -127,7 +125,6 @@ protected:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/DigitalInOut.h

@@ -22,11 +22,9 @@
 #include "hal/gpio_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_DigitalInOut DigitalInOut class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -154,7 +152,6 @@ protected:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/DigitalOut.h

@@ -21,11 +21,9 @@
 #include "hal/gpio_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_DigitalOut DigitalOut class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -148,7 +146,6 @@ protected:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/Ethernet.h

@@ -23,7 +23,7 @@
 #if DEVICE_ETHERNET || defined(DOXYGEN_ONLY)
 
 namespace mbed {
-/** \ingroup drivers */
+/** \ingroup mbed-os-public */
 /** \addtogroup drivers-public-api */
 /** @{*/
 /**

drivers/FlashIAP.h

@@ -49,7 +49,7 @@ extern uint32_t Load$$LR$$LR_IROM1$$Limit[];
 
 namespace mbed {
 
-/** \ingroup drivers */
+/** \ingroup mbed-os-public */
 /** \addtogroup drivers-public-api */
 /** @{*/
 /**

drivers/I2C.h

@@ -34,11 +34,13 @@
 #endif
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
+/** \defgroup drivers-public-api-i2c I2C
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_I2C I2C class
+ * \ingroup drivers-public-api-i2c
  * @{
  */
 
@@ -247,7 +249,6 @@ private:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/I2CSlave.h

@@ -24,11 +24,9 @@
 #include "hal/i2c_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_I2CSlave I2CSlave class
+ * \addtogroup drivers_I2CSlave I2CSlave class
+ * \ingroup drivers-public-api-i2c
  * @{
  */
 
@@ -165,7 +163,6 @@ protected:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/InterruptIn.h

@@ -29,11 +29,13 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
+/** \defgroup drivers-public-api-interrupt Interrupt
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_InterruptIn InterruptIn class
+ * \ingroup drivers-public-api-interrupt
  * @{
  */
 
@@ -180,7 +182,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/InterruptManager.h

@@ -24,11 +24,9 @@
 #include <string.h>
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_InterruptManager InterruptManager class
+ * \ingroup drivers-public-api-interrupt
  * @{
  */
 
@@ -209,7 +207,6 @@ private:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/LowPowerTicker.h

@@ -26,11 +26,13 @@
 #include "hal/lp_ticker_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
+/** \defgroup drivers-public-api-ticker Ticker
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_LowPowerTicker LowPowerTicker class
+ * \ingroup drivers-public-api-ticker
  * @{
  */
 
@@ -50,7 +52,6 @@ public:
     }
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/LowPowerTimeout.h

@@ -26,11 +26,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_LowPowerTimeout LowPowerTimeout class
+ * \addtogroup drivers_LowPowerTimeout LowPowerTimeout class
+ * \ingroup drivers-public-api-ticker
  * @{
  */
 
@@ -48,7 +46,6 @@ private:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/LowPowerTimer.h

@@ -26,11 +26,9 @@
 #include "hal/lp_ticker_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_LowPowerTimer LowPowerTimer class
+ * \addtogroup drivers_LowPowerTimer LowPowerTimer class
+ * \ingroup drivers-public-api-ticker
  * @{
  */
 
@@ -47,7 +45,6 @@ public:
 
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/MbedCRC.h

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

drivers/PortIn.h

@@ -24,11 +24,9 @@
 #include "hal/port_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_PortIn PortIn class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -94,7 +92,6 @@ private:
     port_t _port;
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/PortInOut.h

@@ -24,11 +24,9 @@
 #include "hal/port_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_PortInOut PortInOut class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -109,7 +107,6 @@ private:
     port_t _port;
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/PortOut.h

@@ -24,13 +24,12 @@
 #include "hal/port_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_PortOut PortOut class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
+
 /** A multiple pin digital output
  *
  * @note Synchronization level: Interrupt safe
@@ -115,7 +114,6 @@ private:
     port_t _port;
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/PwmOut.h

@@ -23,11 +23,9 @@
 #include "hal/pwmout_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_PwmOut PwmOut class
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 
@@ -162,7 +160,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/QSPI.h

@@ -29,12 +29,13 @@
 #define ONE_MHZ     1000000
 
 namespace mbed {
+/** \defgroup drivers-public-api-spi SPI
+ * \ingroup drivers-public-api
+ */
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_QSPI QSPI class
+ * \ingroup drivers-public-api-spi
  * @{
  */
 
@@ -230,7 +231,6 @@ private:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/RawSerial.h

@@ -27,11 +27,13 @@
 #include <cstdarg>
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
+/** \defgroup drivers-public-api-uart UART
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_RawSerial RawSerial class
+ * \ingroup drivers-public-api-uart
  * @{
  */
 
@@ -109,7 +111,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/ResetReason.h

@@ -22,7 +22,7 @@
 #include "reset_reason_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
+/** \ingroup mbed-os-public */
 /** \addtogroup drivers-public-api */
 /** @{*/
 /**

drivers/SPI.h

@@ -45,11 +45,9 @@
 #endif
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_SPI SPI class
+ * \addtogroup drivers_SPI SPI class
+ * \ingroup drivers-public-api-spi
  * @{
  */
 
@@ -430,7 +428,6 @@ private:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/SPISlave.h

@@ -25,11 +25,9 @@
 #include "hal/spi_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_SPISlave SPISlave class
+ * \ingroup drivers-public-api-spi
  * @{
  */
 
@@ -132,7 +130,6 @@ protected:
 #endif //!defined(DOXYGEN_ONLY)
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/Serial.h

@@ -27,11 +27,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_Serial Serial class
+ * \ingroup drivers-public-api-uart
  * @{
  */
 
@@ -115,7 +113,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/SerialBase.h

@@ -32,12 +32,9 @@
 #endif
 
 namespace mbed {
-/** \defgroup drivers */
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_SerialBase SerialBase class
+ * \ingroup drivers-public-api-uart
  * @{
  */
 
@@ -314,7 +311,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/SerialWireOutput.h

@@ -25,11 +25,9 @@
 #include "platform/FileHandle.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api Public API */
-/** @{*/
 /**
  * \defgroup drivers_SerialWireOutput SerialWireOutput class
+ * \ingroup drivers-public-api-uart
  * @{
  */
 
@@ -71,7 +69,6 @@ public:
     }
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/Ticker.h

@@ -24,11 +24,9 @@
 #include "hal/lp_ticker_api.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_Ticker Ticker class
+ * \addtogroup drivers_Ticker Ticker class
+ * \ingroup drivers-public-api-ticker
  * @{
  */
 
@@ -154,7 +152,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/Timeout.h

@@ -21,11 +21,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_Timeout Timeout class
+ * \addtogroup drivers_Timeout Timeout class
+ * \ingroup drivers-public-api-ticker
  * @{
  */
 
@@ -67,7 +65,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/Timer.h

@@ -22,11 +22,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_Timer Timer class
+ * \addtogroup drivers_Timer Timer class
+ * \ingroup drivers-public-api-ticker
  * @{
  */
 
@@ -112,7 +110,6 @@ protected:
 };
 #endif
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/TimerEvent.h

@@ -21,11 +21,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
- * \defgroup drivers_TimerEvent TimerEvent class
+ * \addtogroup drivers_TimerEvent TimerEvent class
+ * \ingroup drivers-public-api-ticker
  * @{
  */
 
@@ -86,7 +84,6 @@ protected:
 #endif
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/UARTSerial.h

@@ -38,12 +38,9 @@
 #endif
 
 namespace mbed {
-
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_UARTSerial UARTSerial class
+ * \ingroup drivers-public-api-uart
  * @{
  */
 
@@ -317,7 +314,6 @@ private:
 
 };
 
-/** @}*/
 /** @}*/
 
 } //namespace mbed

drivers/USBAudio.h

@@ -28,11 +28,13 @@
 #include "ByteBuffer.h"
 #include "rtos/EventFlags.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
+/** \defgroup drivers-public-api-usb USB
+ * \ingroup drivers-public-api
+ */
+
 /**
  * \defgroup drivers_USBAudio USBAudio class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -382,7 +384,6 @@ private:
 
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBCDC.h

@@ -27,11 +27,9 @@
 
 class AsyncOp;
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBCDC USBCDC class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -232,7 +230,6 @@ protected:
     uint32_t _rx_size;
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBCDC_ECM.h

@@ -38,11 +38,9 @@
 #define PACKET_TYPE_BROADCAST       (1<<3)
 #define PACKET_TYPE_MULTICAST       (1<<4)
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBCDC_ECM USBCDC_ECM class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -275,7 +273,6 @@ private:
     void _notify_connect();
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBHID.h

@@ -25,12 +25,9 @@
 #include "USBHID_Types.h"
 #include "OperationList.h"
 
-
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBHID USBHID class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -275,7 +272,6 @@ private:
 
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBKeyboard.h

@@ -74,11 +74,9 @@ enum FUNCTION_KEY {
     UP_ARROW,           /* Up arrow */
 };
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBKeyboard USBKeyboard class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -217,7 +215,6 @@ private:
 
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBMIDI.h

@@ -30,11 +30,9 @@
 
 #define DEFAULT_CONFIGURATION (1)
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBMIDI USBMIDI class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -190,7 +188,6 @@ private:
     bool _next_message();
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBMSD.h

@@ -29,11 +29,9 @@
 
 #include "USBDevice.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBMSD USBMSD class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -312,7 +310,6 @@ private:
     void fail();
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBMouse.h

@@ -49,11 +49,9 @@ enum MOUSE_TYPE {
     REL_MOUSE,
 };
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBMouse USBMouse class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -240,7 +238,6 @@ private:
     bool mouse_send(int8_t x, int8_t y, uint8_t buttons, int8_t z);
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBMouseKeyboard.h

@@ -28,11 +28,9 @@
 #include "USBHID.h"
 #include "PlatformMutex.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBMouseKeyboard USBMouseKeyboard class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -251,7 +249,6 @@ private:
     virtual int _getc();
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/USBSerial.h

@@ -22,11 +22,9 @@
 #include "Stream.h"
 #include "Callback.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_USBSerial USBSerial class
+ * \ingroup drivers-public-api-usb
  * @{
  */
 
@@ -224,7 +222,6 @@ private:
     void (*_settings_changed_callback)(int baud, int bits, int parity, int stop);
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/Watchdog.h

@@ -28,7 +28,7 @@
 #include <cstdio>
 
 namespace mbed {
-/** \ingroup drivers */
+/** \ingroup mbed-os-public */
 /** \addtogroup drivers-public-api */
 /** @{*/
 /**

drivers/internal/AsyncOp.h

@@ -25,11 +25,15 @@
 #include "LinkEntry.h"
 #include "OperationListBase.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
+/** \defgroup mbed-os-internal Internal API */
+
+/** \addtogroup drivers-internal-api Drivers
+ * \ingroup mbed-os-internal
+ */
+
 /**
  * \defgroup drivers_AsyncOp AsyncOp class
+ * \ingroup drivers-internal-api
  * @{
  */
 class AsyncOp: public LinkEntry {
@@ -116,7 +120,6 @@ private:
     static void _host_unlock(rtos::Mutex *host_mutex);
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/internal/ByteBuffer.h

@@ -20,11 +20,9 @@
 
 #include <stdint.h>
 
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
 /**
  * \defgroup drivers_ByteBuffer ByteBuffer class
+ * \ingroup drivers-internal-api
  * @{
  */
 class ByteBuffer {
@@ -123,7 +121,6 @@ private:
     uint8_t *_buf;
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/internal/EndpointResolver.h

@@ -20,6 +20,12 @@
 
 #include "USBPhy.h"
 
+/**
+ * \defgroup drivers_EndpointResolver EndpointResolver class
+ * \ingroup drivers-internal-api
+ * @{
+ */
+
 /**
  * Utility class for resolving endpoints
  *
@@ -30,14 +36,6 @@
  * given configuration.
  *
  */
-
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
-/**
- * \defgroup drivers_EndpointResolver EndpointResolver class
- * @{
- */
 class EndpointResolver {
 public:
     EndpointResolver(const usb_ep_table_t *table);
@@ -96,7 +94,6 @@ private:
     bool _valid;
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/internal/LinkEntry.h

@@ -20,11 +20,9 @@
 
 #include <cstddef>
 
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
 /**
  * \defgroup drivers_LinkEntry LinkEntry class
+ * \ingroup drivers-internal-api-list
  * @{
  */
 class LinkEntry {
@@ -39,7 +37,6 @@ private:
     LinkEntry *_next;
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/internal/LinkedList.h

@@ -21,11 +21,13 @@
 #include "LinkEntry.h"
 #include "LinkedListBase.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
+/** \defgroup drivers-internal-api-list List
+ * \ingroup drivers-internal-api
+ */
+
 /**
  * \defgroup drivers_LinkedList LinkedList class
+ * \ingroup drivers-internal-api-list
  * @{
  */
 template<class T>
@@ -65,7 +67,6 @@ public:
     }
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/internal/LinkedListBase.h

@@ -20,11 +20,9 @@
 
 #include "LinkEntry.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
 /**
  * \defgroup drivers_LinkedListBase LinkedListBase class
+ * \ingroup drivers-internal-api-list
  * @{
  */
 class LinkedListBase {
@@ -65,7 +63,6 @@ private:
     LinkEntry *_tail;
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/internal/MIDIMessage.h

@@ -40,11 +40,10 @@
 
 #define CABLE_NUM (0<<4)
 
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
+
 /**
  * \defgroup drivers_MIDIMessage MIDIMessage class
+ * \ingroup drivers-internal-api
  * @{
  */
 
@@ -480,7 +479,6 @@ public:
     uint16_t length;
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/internal/PolledQueue.h

@@ -22,9 +22,17 @@
 #include "platform/Callback.h"
 #include "LinkedList.h"
 namespace events {
-/** \ingroup events */
-/** \addtogroup events-internal-api */
-/** @{*/
+/** \addtogroup events-internal-api Events
+ * \ingroup mbed-os-internal
+ * @{
+ */
+
+
+/**
+ * \defgroup events_PolledQueue PolledQueue class
+ * \ingroup events-internal-api
+ * @{
+ */
 
 /** PolledQueue
  *
@@ -67,6 +75,7 @@ protected:
 
 };
 
+/** @}*/
 /** @}*/
 
 }

drivers/internal/TableCRC.h

@@ -21,9 +21,10 @@
 #include <stdint.h>
 
 namespace mbed {
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api Internal API */
-/** @{*/
+/** \addtogroup drivers-internal-api
+ * \ingroup mbed-os-internal
+ * @{
+ */
 
 #define MBED_CRC_TABLE_SIZE             256
 #define MBED_OPTIMIZED_CRC_TABLE_SIZE   16

drivers/internal/Task.h

@@ -24,9 +24,10 @@
 #include "platform/Callback.h"
 
 namespace events {
-/** \ingroup events */
-/** \addtogroup events-internal-api */
-/** @{*/
+/** \addtogroup events-internal-api
+ * \ingroup mbed-os-internal
+ * @{
+ */
 
 
 template<typename F, typename A1 = void, typename A2 = void, typename A3 = void, typename A4 = void, typename A5 = void>

drivers/internal/TaskBase.h

@@ -27,13 +27,15 @@ class Semaphore;
 }
 
 namespace events {
-/** \ingroup events */
-/** \addtogroup events-internal-api */
-/** @{*/
-
 
 class TaskQueue;
 
+/**
+ * \defgroup events_TaskBase TaskBase class
+ * \ingroup events-internal-api
+ * @{
+ */
+
 /** TaskBase
  *
  *  Representation of a caller allocated task

drivers/internal/TaskQueue.h

@@ -25,11 +25,12 @@
 #define MBED_MAX_TASK_SIZE  32
 
 namespace events {
-/** \ingroup events */
-/** \addtogroup events-internal-api */
-/** @{*/
-
 
+/**
+ * \defgroup events_TaskQueue TaskQueue class
+ * \ingroup events-internal-api
+ * @{
+ */
 
 /** TaskQueue
  *

events/Event.h

@@ -21,9 +21,11 @@
 #include "platform/mbed_assert.h"
 
 namespace events {
-/** \ingroup events */
-/** \addtogroup events-public-api Public API */
-/** @{*/
+/**
+ * \addtogroup events-public-api Events
+ * \ingroup mbed-os-public
+ * @{
+ */
 
 /** Event
  *

events/EventQueue.h

@@ -18,16 +18,17 @@
 #ifndef EVENT_QUEUE_H
 #define EVENT_QUEUE_H
 
-#include "events/internal/equeue.h"
+#include "events/equeue.h"
 #include "platform/Callback.h"
 #include "platform/NonCopyable.h"
 #include <cstddef>
 #include <new>
 
 namespace events {
-/** \ingroup events */
-/** \addtogroup events-public-api */
-/** @{*/
+/**
+ * \addtogroup events-public-api
+ * @{
+ */
 
 /** EVENTS_EVENT_SIZE
  *  Minimum size of an event

events/README.md

@@ -150,4 +150,215 @@ b.chain(&a);
 a.dispatch();
 ```
 
+## Underlying C API ##
+
+The `mbed-events` C++ library is the recommended library for scheduling events. However, for occasions where C++ cannot be used for a project (e.g bare metal), the underlying C API `equeue` used by `mbed-events` can be accessed directly.
+
+The `equeue` library is designed as a simple but powerful library for scheduling
+events on composable queues.
+
+``` c
+#include "equeue.h"
+#include <stdio.h>
+
+int main() {
+    // creates a queue with space for 32 basic events
+    equeue_t queue;
+    equeue_create(&queue, 32*EQUEUE_EVENT_SIZE);
+
+    // events can be simple callbacks
+    equeue_call(&queue, print, "called immediately");
+    equeue_call_in(&queue, 2000, print, "called in 2 seconds");
+    equeue_call_every(&queue, 1000, print, "called every 1 seconds");
+
+    // events are executed in equeue_dispatch
+    equeue_dispatch(&queue, 3000);
+
+    print("called after 3 seconds");
+
+    equeue_destroy(&queue);
+}
+```
+
+The equeue library can be used as a normal event loop, or it can be
+backgrounded on a single hardware timer or even another event loop. It
+is both thread and irq safe, and provides functions for easily composing
+multiple queues.
+
+The equeue library can act as a drop-in scheduler, provide synchronization
+between multiple threads, or just act as a mechanism for moving events
+out of interrupt contexts.
+
+## Documentation ##
+
+The in-depth documentation on specific functions can be found in
+[equeue.h](equeue.h).
+
+The core of the equeue library is the `equeue_t` type which represents a
+single event queue, and the `equeue_dispatch` function which runs the equeue,
+providing the context for executing events.
+
+On top of this, `equeue_call`, `equeue_call_in`, and `equeue_call_every`
+provide easy methods for posting events to execute in the context of the
+`equeue_dispatch` function.
+
+``` c
+#include "equeue.h"
+#include "game.h"
+
+equeue_t queue;
+struct game game;
+
+// button_isr may be in interrupt context
+void button_isr(void) {
+    equeue_call(&queue, game_button_update, &game);
+}
+
+// a simple user-interface framework
+int main() {
+    equeue_create(&queue, 4096);
+    game_create(&game);
+
+    // call game_screen_udpate at 60 Hz
+    equeue_call_every(&queue, 1000/60, game_screen_update, &game);
+
+    // dispatch forever
+    equeue_dispatch(&queue, -1);
+}
+```
+
+In addition to simple callbacks, an event can be manually allocated with
+`equeue_alloc` and posted with `equeue_post` to allow passing an arbitrary
+amount of context to the execution of the event. This memory is allocated out
+of the equeue's buffer, and dynamic memory can be completely avoided.
+
+The equeue allocator is designed to minimize jitter in interrupt contexts as
+well as avoid memory fragmentation on small devices. The allocator achieves
+both constant-runtime and zero-fragmentation for fixed-size events, however
+grows linearly as the quantity of differently-sized allocations increases.
+
+``` c
+#include "equeue.h"
+
+equeue_t queue;
+
+// arbitrary data can be moved to a different context
+int enet_consume(void *buffer, int size) {
+    if (size > 512) {
+        size = 512;
+    }
+
+    void *data = equeue_alloc(&queue, 512);
+    memcpy(data, buffer, size);
+    equeue_post(&queue, handle_data_elsewhere, data);
+
+    return size;
+}
+```
+
+Additionally, in-flight events can be cancelled with `equeue_cancel`. Events
+are given unique ids on post, allowing safe cancellation of expired events.
+
+``` c
+#include "equeue.h"
+
+equeue_t queue;
+int sonar_value;
+int sonar_timeout_id;
+
+void sonar_isr(int value) {
+    equeue_cancel(&queue, sonar_timeout_id);
+    sonar_value = value;
+}
+
+void sonar_timeout(void *) {
+    sonar_value = -1;
+}
+
+void sonar_read(void) {
+    sonar_timeout_id = equeue_call_in(&queue, 300, sonar_timeout, 0);
+    sonar_start();
+}
+```
+
+From an architectural standpoint, event queues easily align with module
+boundaries, where internal state can be implicitly synchronized through
+event dispatch.
+
+On platforms where multiple threads are unavailable, multiple modules
+can use independent event queues and still be composed through the
+`equeue_chain` function.
+
+``` c
+#include "equeue.h"
+
+// run a simultaneous localization and mapping loop in one queue
+struct slam {
+    equeue_t queue;
+};
+
+void slam_create(struct slam *s, equeue_t *target) {
+    equeue_create(&s->queue, 4096);
+    equeue_chain(&s->queue, target);
+    equeue_call_every(&s->queue, 100, slam_filter);
+}
+
+// run a sonar with it's own queue
+struct sonar {
+    equeue_t equeue;
+    struct slam *slam;
+};
+
+void sonar_create(struct sonar *s, equeue_t *target) {
+    equeue_create(&s->queue, 64);
+    equeue_chain(&s->queue, target);
+    equeue_call_in(&s->queue, 5, sonar_update, s);
+}
+
+// all of the above queues can be combined into a single thread of execution
+int main() {
+    equeue_t queue;
+    equeue_create(&queue, 1024);
+
+    struct sonar s1, s2, s3;
+    sonar_create(&s1, &queue);
+    sonar_create(&s2, &queue);
+    sonar_create(&s3, &queue);
+
+    struct slam slam;
+    slam_create(&slam, &queue);
+
+    // dispatches events from all of the modules
+    equeue_dispatch(&queue, -1);
+}
+```
+
+## Platform ##
+
+The equeue library has a minimal porting layer that is flexible depending
+on the requirements of the underlying platform. Platform specific declarations
+and more information can be found in [equeue_platform.h](equeue_platform.h).
+
+## Tests ##
+
+The equeue library uses a set of local tests based on the posix implementation.
+
+Runtime tests are located in [tests.c](tests/tests.c):
+
+``` bash
+make test
+```
+
+Profiling tests based on rdtsc are located in [prof.c](tests/prof.c):
+
+``` bash
+make prof
+```
+
+To make profiling results more tangible, the profiler also supports percentage
+comparison with previous runs:
+``` bash
+make prof | tee results.txt
+cat results.txt | make prof
+```
 

events/equeue.h

@@ -29,9 +29,10 @@ extern "C" {
 #include <stddef.h>
 #include <stdint.h>
 
-/** \ingroup events */
-/** \addtogroup events-internal-api Internal API */
-/** @{*/
+/**
+ * \addtogroup events-public-api
+ * @{
+ */
 
 // The minimum size of an event
 // This size is guaranteed to fit events created by event_call

events/internal/equeue_platform.h

@@ -25,9 +25,11 @@ extern "C" {
 #include <stdbool.h>
 #include <stdint.h>
 
-/** \ingroup events */
-/** \addtogroup events-internal-api */
-/** @{*/
+/**
+ * \addtogroup events-internal-api Events
+ * \ingroup mbed-os-internal
+ * @{
+ */
 
 // Currently supported platforms
 //

events/mbed_events.h

@@ -1,5 +1,3 @@
-/** \addtogroup events */
-/** @{*/
 /* Copyright (c) 2016-2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -25,13 +23,14 @@
 
 #include "events/mbed_shared_queues.h"
 
+/** \ingroup mbed-os-internal */
+/** \addtogroup events-internal-api */
+/** @{*/
 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
 using namespace events;
 #endif
-
-#endif
-
-
-#endif
-
 /** @}*/
+
+#endif
+
+#endif

events/mbed_shared_queues.h

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

events/source/README.md

@@ -1,209 +0,0 @@
-## The equeue library ##
-
-The equeue library is designed as a simple but powerful library for scheduling
-events on composable queues.
-
-``` c
-#include "equeue.h"
-#include <stdio.h>
-
-int main() {
-    // creates a queue with space for 32 basic events
-    equeue_t queue;
-    equeue_create(&queue, 32*EQUEUE_EVENT_SIZE);
-
-    // events can be simple callbacks
-    equeue_call(&queue, print, "called immediately");
-    equeue_call_in(&queue, 2000, print, "called in 2 seconds");
-    equeue_call_every(&queue, 1000, print, "called every 1 seconds");
-
-    // events are executed in equeue_dispatch
-    equeue_dispatch(&queue, 3000);
-
-    print("called after 3 seconds");
-
-    equeue_destroy(&queue);
-}
-```
-
-The equeue library can be used as a normal event loop, or it can be
-backgrounded on a single hardware timer or even another event loop. It
-is both thread and irq safe, and provides functions for easily composing
-multiple queues.
-
-The equeue library can act as a drop-in scheduler, provide synchronization
-between multiple threads, or just act as a mechanism for moving events
-out of interrupt contexts.
-
-## Documentation ##
-
-The in-depth documentation on specific functions can be found in
-[equeue.h](equeue.h).
-
-The core of the equeue library is the `equeue_t` type which represents a
-single event queue, and the `equeue_dispatch` function which runs the equeue,
-providing the context for executing events.
-
-On top of this, `equeue_call`, `equeue_call_in`, and `equeue_call_every`
-provide easy methods for posting events to execute in the context of the
-`equeue_dispatch` function.
-
-``` c
-#include "equeue.h"
-#include "game.h"
-
-equeue_t queue;
-struct game game;
-
-// button_isr may be in interrupt context
-void button_isr(void) {
-    equeue_call(&queue, game_button_update, &game);
-}
-
-// a simple user-interface framework
-int main() {
-    equeue_create(&queue, 4096);
-    game_create(&game);
-
-    // call game_screen_udpate at 60 Hz
-    equeue_call_every(&queue, 1000/60, game_screen_update, &game);
-
-    // dispatch forever
-    equeue_dispatch(&queue, -1);
-}
-```
-
-In addition to simple callbacks, an event can be manually allocated with
-`equeue_alloc` and posted with `equeue_post` to allow passing an arbitrary
-amount of context to the execution of the event. This memory is allocated out
-of the equeue's buffer, and dynamic memory can be completely avoided.
-
-The equeue allocator is designed to minimize jitter in interrupt contexts as
-well as avoid memory fragmentation on small devices. The allocator achieves
-both constant-runtime and zero-fragmentation for fixed-size events, however
-grows linearly as the quantity of differently-sized allocations increases.
-
-``` c
-#include "equeue.h"
-
-equeue_t queue;
-
-// arbitrary data can be moved to a different context
-int enet_consume(void *buffer, int size) {
-    if (size > 512) {
-        size = 512;
-    }
-
-    void *data = equeue_alloc(&queue, 512);
-    memcpy(data, buffer, size);
-    equeue_post(&queue, handle_data_elsewhere, data);
-
-    return size;
-}
-```
-
-Additionally, in-flight events can be cancelled with `equeue_cancel`. Events
-are given unique ids on post, allowing safe cancellation of expired events.
-
-``` c
-#include "equeue.h"
-
-equeue_t queue;
-int sonar_value;
-int sonar_timeout_id;
-
-void sonar_isr(int value) {
-    equeue_cancel(&queue, sonar_timeout_id);
-    sonar_value = value;
-}
-
-void sonar_timeout(void *) {
-    sonar_value = -1;
-}
-
-void sonar_read(void) {
-    sonar_timeout_id = equeue_call_in(&queue, 300, sonar_timeout, 0);
-    sonar_start();
-}
-```
-
-From an architectural standpoint, event queues easily align with module
-boundaries, where internal state can be implicitly synchronized through
-event dispatch.
-
-On platforms where multiple threads are unavailable, multiple modules
-can use independent event queues and still be composed through the
-`equeue_chain` function.
-
-``` c
-#include "equeue.h"
-
-// run a simultaneous localization and mapping loop in one queue
-struct slam {
-    equeue_t queue;
-};
-
-void slam_create(struct slam *s, equeue_t *target) {
-    equeue_create(&s->queue, 4096);
-    equeue_chain(&s->queue, target);
-    equeue_call_every(&s->queue, 100, slam_filter);
-}
-
-// run a sonar with it's own queue
-struct sonar {
-    equeue_t equeue;
-    struct slam *slam;
-};
-
-void sonar_create(struct sonar *s, equeue_t *target) {
-    equeue_create(&s->queue, 64);
-    equeue_chain(&s->queue, target);
-    equeue_call_in(&s->queue, 5, sonar_update, s);
-}
-
-// all of the above queues can be combined into a single thread of execution
-int main() {
-    equeue_t queue;
-    equeue_create(&queue, 1024);
-
-    struct sonar s1, s2, s3;
-    sonar_create(&s1, &queue);
-    sonar_create(&s2, &queue);
-    sonar_create(&s3, &queue);
-
-    struct slam slam;
-    slam_create(&slam, &queue);
-
-    // dispatches events from all of the modules
-    equeue_dispatch(&queue, -1);
-}
-```
-
-## Platform ##
-
-The equeue library has a minimal porting layer that is flexible depending
-on the requirements of the underlying platform. Platform specific declarations
-and more information can be found in [equeue_platform.h](equeue_platform.h).
-
-## Tests ##
-
-The equeue library uses a set of local tests based on the posix implementation.
-
-Runtime tests are located in [tests.c](tests/tests.c):
-
-``` bash
-make test
-```
-
-Profiling tests based on rdtsc are located in [prof.c](tests/prof.c):
-
-``` bash
-make prof
-```
-
-To make profiling results more tangible, the profiler also supports percentage
-comparison with previous runs:
-``` bash
-make prof | tee results.txt
-cat results.txt | make prof
-```

events/source/equeue.c

@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#include "events/internal/equeue.h"
+#include "events/equeue.h"
 
 #include <stdlib.h>
 #include <stdint.h>

events/source/tests/prof.c

@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#include "events/internal/equeue.h"
+#include "events/equeue.h"
 #include <unistd.h>
 #include <stdio.h>
 #include <setjmp.h>

events/source/tests/tests.c

@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#include "events/internal/equeue.h"
+#include "events/equeue.h"
 #include <unistd.h>
 #include <stdio.h>
 #include <setjmp.h>

platform/ATCmdParser.h

@@ -28,8 +28,8 @@
 
 namespace mbed {
 
-/** \ingroup platform */
-/** \addtogroup platform-public-api Public API */
+/** \ingroup mbed-os-public */
+/** \addtogroup platform-public-api Platform */
 /** @{*/
 /**
  * \defgroup platform_ATCmdParser ATCmdParser class

platform/CThunk.h

@@ -1,4 +1,4 @@
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/Callback.h

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

platform/CircularBuffer.h

@@ -51,7 +51,7 @@ struct is_unsigned<unsigned long long> {
 };
 };
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/CriticalSectionLock.h

@@ -22,7 +22,7 @@
 
 namespace mbed {
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/DeepSleepLock.h

@@ -22,7 +22,7 @@
 
 namespace mbed {
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/DirHandle.h

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

platform/FileBase.h

@@ -31,13 +31,16 @@ typedef enum {
     FileSystemPathType
 } PathType;
 
-/** \ingroup platform */
-/** \addtogroup platform-public-api */
-/** @{*/
+/** \defgroup platform-public-api-file File
+ * \ingroup platform-public-api
+ */
+
 /**
  * \defgroup platform_FileBase FileBase class
+ * \ingroup platform-public-api-file
  * @{
  */
+
 /** Class FileBase
  *
  */
@@ -68,8 +71,6 @@ private:
 
 /**@}*/
 
-/**@}*/
-
 } // namespace mbed
 
 #endif

platform/FileHandle.h

@@ -26,11 +26,10 @@ typedef int FILEHANDLE;
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup platform */
-/** \addtogroup platform-public-api */
-/** @{*/
+
 /**
  * \defgroup platform_FileHandle FileHandle functions
+ * \ingroup platform-public-api-file
  * @{
  */
 
@@ -320,9 +319,6 @@ public:
 
 /**@}*/
 
-/**@}*/
-
-
 } // namespace mbed
 
 #endif

platform/FileLike.h

@@ -22,13 +22,12 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup platform */
-/** \addtogroup platform-public-api */
-/** @{*/
 /**
  * \defgroup platform_FileLike FileLike class
+ * \ingroup platform-public-api-file
  * @{
  */
+
 /** Class FileLike
  *
  *  A file-like object is one that can be opened with fopen by
@@ -48,8 +47,6 @@ public:
 
 /**@}*/
 
-/**@}*/
-
 } // namespace mbed
 
 #endif

platform/FilePath.h

@@ -23,19 +23,18 @@
 #include "platform/FileLike.h"
 
 namespace mbed {
-/** \ingroup platform */
-/** \addtogroup platform-public-api */
-/** @{*/
+
+class FileSystem;
+
 /**
  * \defgroup platform_FilePath FilePath class
+ * \ingroup platform-public-api-file
  * @{
  */
 
-class FileSystem;
 /** Class FilePath
  *
  */
-
 class FilePath {
 public:
     /** Constructor FilePath
@@ -60,8 +59,6 @@ private:
 
 /**@}*/
 
-/**@}*/
-
 } // namespace mbed
 
 #endif

platform/FileSystemHandle.h

@@ -24,11 +24,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup platform */
-/** \addtogroup platform-public-api */
-/** @{*/
 /**
  * \defgroup platform_FileSystemHandle FileSystemHandle functions
+ * \ingroup platform-public-api-file
  * @{
  */
 
@@ -106,8 +104,6 @@ public:
 };
 /**@}*/
 
-/**@}*/
-
 } // namespace mbed
 
 #endif

platform/FileSystemLike.h

@@ -26,11 +26,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \ingroup platform */
-/** \addtogroup platform-public-api */
-/** @{*/
 /**
  * \defgroup platform_FileSystemLike FileSystemLike functions
+ * \ingroup platform-public-api-file
  * @{
  */
 
@@ -88,8 +86,6 @@ public:
 
 /**@}*/
 
-/**@}*/
-
 } // namespace mbed
 
 #endif

platform/FunctionPointer.h

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

platform/LocalFileSystem.h

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

platform/NonCopyable.h

@@ -24,7 +24,7 @@
 
 namespace mbed {
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/PlatformMutex.h

@@ -19,7 +19,7 @@
 
 #include "platform/NonCopyable.h"
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 

platform/ScopedLock.h

@@ -21,7 +21,7 @@
 
 namespace mbed {
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/ScopedRamExecutionLock.h

@@ -21,7 +21,7 @@
 
 namespace mbed {
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 

platform/ScopedRomWriteLock.h

@@ -21,7 +21,7 @@
 
 namespace mbed {
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 

platform/SingletonPtr.h

@@ -1,5 +1,5 @@
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/Span.h

@@ -26,7 +26,7 @@
 
 namespace mbed {
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/Stream.h

@@ -25,7 +25,7 @@
 #include <cstdarg>
 
 namespace mbed {
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/Transaction.h

@@ -20,7 +20,7 @@
 #include "platform/platform.h"
 
 namespace mbed {
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/internal/CThunkBase.h

@@ -21,7 +21,7 @@
 /* IRQ/Exception compatible thunk entry function */
 typedef void (*CThunkEntry)(void);
 
-/** \ingroup platform */
+/** \ingroup mbed-os-internal */
 /** \addtogroup platform-internal-api */
 /** @{*/
 /**

platform/internal/CallChain.h

@@ -28,8 +28,8 @@ namespace mbed {
 typedef Callback<void()> *pFunctionPointer_t;
 class CallChainLink;
 
-/** \ingroup platform */
-/** \addtogroup platform-internal-api Internal API */
+/** \ingroup mbed-os-internal */
+/** \addtogroup platform-internal-api Platform */
 /** @{*/
 /**
  * \defgroup platform_CallChain CallChain class

platform/mbed_assert.h

@@ -1,5 +1,5 @@
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**

platform/mbed_atomic.h

@@ -26,7 +26,7 @@
 #include <stddef.h>
 #include "platform/mbed_toolchain.h"
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 

platform/mbed_critical.h

@@ -25,7 +25,7 @@
 extern "C" {
 #endif
 
-/** \ingroup platform */
+/** \ingroup mbed-os-public */
 /** \addtogroup platform-public-api */
 /** @{*/
 /**