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`

Author: hugueskamba

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 @@ class
 
     /** 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 @@ class
      *  @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 @@ class
      *    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 @@ class
      *    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 @@ class
      *  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 @@ class
      * }
      * @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 @@ class
      *
      *  @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,15 +18,15 @@
 #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>
 
 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 @@ class Watchdog : private NonCopyable<Watchdog>  {
     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 {