Upstream PR #11073 review request changes (#11135)

* Modify Doxygen grouping of `drivers` Public/Internal APIs
* Correct classification of `mbed_events.h`
* Amend name of Doxygen group containing Device Key API
* Classify `CallChain.h` as public API and relocate file
* Remove Doxygen group from `equeue_platform.h` as it has no Doxygen compliant documentation
* Move USB target specific code back to `usb/device/targets`

drivers/BusIn.h

@@ -23,13 +23,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \defgroup drivers-public-api-bus Bus
- * \ingroup drivers-public-api
- */
-
 /**
  * \defgroup drivers_BusIn BusIn class
- * \ingroup drivers-public-api-bus
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 

drivers/BusInOut.h

@@ -24,7 +24,7 @@
 namespace mbed {
 /**
  * \defgroup drivers_BusInOut BusInOut class
- * \ingroup drivers-public-api-bus
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 

drivers/BusOut.h

@@ -24,7 +24,7 @@
 namespace mbed {
 /**
  * \defgroup drivers_BusOut BusOut class
- * \ingroup drivers-public-api-bus
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 

drivers/Ethernet.h

@@ -32,6 +32,11 @@ namespace mbed {
  */
 
 /** An ethernet interface, to use with the ethernet pins.
+ *
+ * @deprecated
+ * EthInterface is now the preferred way to get an Ethernet object.
+ * Alternatively, use NetworkInterface to get an instance of an appropriate network
+ * interface (WiFi or Ethernet).
  *
  * @note Synchronization level: Not protected
  *
@@ -72,10 +77,12 @@ public:
 
     /** Initialize the ethernet interface.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     Ethernet();
 
     /** Powers the hardware down.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     virtual ~Ethernet();
 
     enum Mode {
@@ -96,6 +103,7 @@ public:
      *  @returns
      *   The number of written bytes.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int write(const char *data, int size);
 
     /** Send an outgoing ethernet packet.
@@ -107,6 +115,7 @@ public:
      *    0 if the sending was failed,
      *    or the size of the packet successfully sent.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int send();
 
     /** Receives an arrived ethernet packet.
@@ -119,6 +128,7 @@ public:
      *    0 if no ethernet packet is arrived,
      *    or the size of the arrived packet.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int receive();
 
     /** Read from an received ethernet packet.
@@ -134,12 +144,14 @@ public:
      *  Each time read will start reading after the last read byte before.
      *
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int read(char *data, int size);
 
     /** Gives the ethernet address of the mbed.
      *
      *  @param mac Must be a pointer to a 6 byte char array to copy the ethernet address in.
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     void address(char *mac);
 
     /** Returns if an ethernet link is present or not. It takes a while after Ethernet initialization to show up.
@@ -165,6 +177,7 @@ public:
      * }
      * @endcode
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     int link();
 
     /** Sets the speed and duplex parameters of an ethernet link
@@ -177,6 +190,7 @@ public:
      *
      *  @param mode the speed and duplex mode to set the link to:
      */
+    MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
     void set_link(Mode mode);
 };
 

drivers/InterruptIn.h

@@ -29,13 +29,9 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \defgroup drivers-public-api-interrupt Interrupt
- * \ingroup drivers-public-api
- */
-
 /**
  * \defgroup drivers_InterruptIn InterruptIn class
- * \ingroup drivers-public-api-interrupt
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 

drivers/InterruptManager.h

@@ -18,7 +18,7 @@
 #define MBED_INTERRUPTMANAGER_H
 
 #include "cmsis.h"
-#include "platform/internal/CallChain.h"
+#include "platform/CallChain.h"
 #include "platform/PlatformMutex.h"
 #include "platform/NonCopyable.h"
 #include <string.h>
@@ -26,7 +26,7 @@
 namespace mbed {
 /**
  * \defgroup drivers_InterruptManager InterruptManager class
- * \ingroup drivers-public-api-interrupt
+ * \ingroup drivers-public-api-gpio
  * @{
  */
 

drivers/SerialWireOutput.h

@@ -27,7 +27,7 @@
 namespace mbed {
 /**
  * \defgroup drivers_SerialWireOutput SerialWireOutput class
- * \ingroup drivers-public-api-uart
+ * \ingroup drivers-public-api
  * @{
  */
 

drivers/Watchdog.h

@@ -28,11 +28,9 @@
 #include <cstdio>
 
 namespace mbed {
-/** \ingroup mbed-os-public */
-/** \addtogroup drivers-public-api */
-/** @{*/
 /**
  * \defgroup drivers_Watchdog Watchdog class
+ * \ingroup drivers-public-api
  * @{
  */
 
@@ -154,7 +152,6 @@ private:
     bool _running;
 };
 
-/** @}*/
 /** @}*/
 
 } // namespace mbed

drivers/internal/AsyncOp.h

@@ -31,9 +31,13 @@
  * \ingroup mbed-os-internal
  */
 
+/** \defgroup drivers-internal-api-usb USB
+ * \ingroup drivers-internal-api
+ */
+
 /**
  * \defgroup drivers_AsyncOp AsyncOp class
- * \ingroup drivers-internal-api
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 class AsyncOp: public LinkEntry {

drivers/internal/ByteBuffer.h

@@ -22,7 +22,7 @@
 
 /**
  * \defgroup drivers_ByteBuffer ByteBuffer class
- * \ingroup drivers-internal-api
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 class ByteBuffer {

drivers/internal/EndpointResolver.h

@@ -22,7 +22,7 @@
 
 /**
  * \defgroup drivers_EndpointResolver EndpointResolver class
- * \ingroup drivers-internal-api
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 

drivers/internal/LinkEntry.h

@@ -22,7 +22,7 @@
 
 /**
  * \defgroup drivers_LinkEntry LinkEntry class
- * \ingroup drivers-internal-api-list
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 class LinkEntry {

drivers/internal/LinkedList.h

@@ -21,13 +21,9 @@
 #include "LinkEntry.h"
 #include "LinkedListBase.h"
 
-/** \defgroup drivers-internal-api-list List
- * \ingroup drivers-internal-api
- */
-
 /**
  * \defgroup drivers_LinkedList LinkedList class
- * \ingroup drivers-internal-api-list
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 template<class T>

drivers/internal/LinkedListBase.h

@@ -22,7 +22,7 @@
 
 /**
  * \defgroup drivers_LinkedListBase LinkedListBase class
- * \ingroup drivers-internal-api-list
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 class LinkedListBase {

drivers/internal/MIDIMessage.h

@@ -43,7 +43,7 @@
 
 /**
  * \defgroup drivers_MIDIMessage MIDIMessage class
- * \ingroup drivers-internal-api
+ * \ingroup drivers-internal-usb
  * @{
  */
 

drivers/internal/OperationList.h

@@ -21,6 +21,11 @@
 #include "OperationListBase.h"
 #include "AsyncOp.h"
 
+/**
+ * \defgroup drivers_OperationList OperationList class
+ * \ingroup drivers-internal-api-usb
+ * @{
+ */
 template<class T>
 class OperationList: public OperationListBase {
 public:
@@ -84,4 +89,6 @@ public:
 
 };
 
+/** @}*/
+
 #endif

drivers/internal/OperationListBase.h

@@ -22,6 +22,11 @@
 
 class AsyncOp;
 
+/**
+ * \defgroup drivers_OperationListBase OperationListBase class
+ * \ingroup drivers-internal-api-usb
+ * @{
+ */
 class OperationListBase {
 public:
 
@@ -93,4 +98,6 @@ private:
     LinkedListBase _list;
 };
 
+/** @}*/
+
 #endif

drivers/internal/PolledQueue.h

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

drivers/internal/Task.h

@@ -24,8 +24,7 @@
 #include "platform/Callback.h"
 
 namespace events {
-/** \addtogroup events-internal-api
- * \ingroup mbed-os-internal
+/** \addtogroup drivers-internal-api-usb
  * @{
  */
 

drivers/internal/TaskBase.h

@@ -31,8 +31,8 @@ namespace events {
 class TaskQueue;
 
 /**
- * \defgroup events_TaskBase TaskBase class
- * \ingroup events-internal-api
+ * \defgroup drivers_TaskBase TaskBase class
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 

drivers/internal/TaskQueue.h

@@ -27,8 +27,8 @@
 namespace events {
 
 /**
- * \defgroup events_TaskQueue TaskQueue class
- * \ingroup events-internal-api
+ * \defgroup drivers_TaskQueue TaskQueue class
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 

drivers/internal/USBDevice.h

@@ -23,11 +23,9 @@
 #include "USBPhy.h"
 #include "mbed_critical.h"
 
-/** \ingroup drivers */
-/** \addtogroup drivers-internal-api */
-/** @{*/
 /**
  * \defgroup drivers_USBDevice USBDevice class
+ * \ingroup drivers-internal-api-usb
  * @{
  */
 
@@ -612,7 +610,6 @@ private:
     uint32_t _locked;
 };
 
-/** @}*/
 /** @}*/
 
 #endif

drivers/source/usb/mbed_lib.json

@@ -1,3 +1,3 @@
 {
-    "name": "usb"
+    "name": "drivers-usb"
 }

events/internal/equeue_platform.h

@@ -25,12 +25,6 @@ extern "C" {
 #include <stdbool.h>
 #include <stdint.h>
 
-/**
- * \addtogroup events-internal-api Events
- * \ingroup mbed-os-internal
- * @{
- */
-
 // Currently supported platforms
 //
 // Uncomment to select a supported platform or reimplement this file
@@ -153,8 +147,6 @@ void equeue_sema_destroy(equeue_sema_t *sema);
 void equeue_sema_signal(equeue_sema_t *sema);
 bool equeue_sema_wait(equeue_sema_t *sema, int ms);
 
-/** @}*/
-
 #ifdef __cplusplus
 }
 #endif

events/mbed_events.h

@@ -23,8 +23,7 @@
 
 #include "events/mbed_shared_queues.h"
 
-/** \ingroup mbed-os-internal */
-/** \addtogroup events-internal-api */
+/** \addtogroup events-public-api */
 /** @{*/
 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
 using namespace events;

features/device_key/source/DeviceKey.h

@@ -32,7 +32,11 @@
 #if (DEVICEKEY_ENABLED) || defined(DOXYGEN_ONLY)
 
 namespace mbed {
-/** \addtogroup device-key Device Key */
+/** \addtogroup device-security Device Key
+ * \ingroup mbed-os-public
+ * @{
+ */
+
 
 #define DEVICE_KEY_16BYTE 16
 #define DEVICE_KEY_32BYTE 32
@@ -58,7 +62,11 @@ enum DeviceKeyStatus {
  * @note Synchronization level: Thread safe
  * @ingroup device-key
  */
-
+/**
+ * \defgroup device-security_DeviceKey DeviceKey class
+ * \addtogroup device-security
+ * @{
+ */
 class DeviceKey : private mbed::NonCopyable<DeviceKey> {
 public:
 
@@ -143,6 +151,8 @@ private:
     int generate_key_by_random(uint32_t *output, size_t size);
 
 };
+
+/** @}*/
 /** @}*/
 
 }

platform/CallChain.h

@@ -28,11 +28,9 @@ namespace mbed {
 typedef Callback<void()> *pFunctionPointer_t;
 class CallChainLink;
 
-/** \ingroup mbed-os-internal */
-/** \addtogroup platform-internal-api Platform */
-/** @{*/
 /**
  * \defgroup platform_CallChain CallChain class
+ * \ingroup platform-public-api
  * @{
  */
 
@@ -260,8 +258,6 @@ private:
 
 /**@}*/
 
-/**@}*/
-
 } // namespace mbed
 
 #endif

platform/internal/CThunkBase.h

@@ -18,14 +18,16 @@
 #ifndef __CTHUNK_BASE_H__
 #define __CTHUNK_BASE_H__
 
+/** \addtogroup platform-internal-api Platform
+ * \ingroup mbed-os-internal
+ */
+
 /* IRQ/Exception compatible thunk entry function */
 typedef void (*CThunkEntry)(void);
 
-/** \ingroup mbed-os-internal */
-/** \addtogroup platform-internal-api */
-/** @{*/
 /**
  * \defgroup platform_CThunkBase CThunkBase class
+ * \ingroup platform-internal-api
  * @{
  */
 class CThunkBase {
@@ -83,6 +85,4 @@ private:
 
 /**@}*/
 
-/**@}*/
-
 #endif/*__CTHUNK_BASE_H__*/

platform/source/CallChain.cpp

@@ -21,7 +21,7 @@
 #undef MBED_DEPRECATED_SINCE
 #define MBED_DEPRECATED_SINCE(...)
 
-#include "platform/internal/CallChain.h"
+#include "platform/CallChain.h"
 #include "cmsis.h"
 #include "platform/mbed_critical.h"
 

usb/device/targets/mbed_lib.json

@@ -0,0 +1,3 @@
+{
+    "name": "usb-device-targets"
+}