Separate drivers internal APIs from public APIs (#5)

* Move source files and internal headers to `internal` dir
* Amend test files and other modules include paths for internal headers
* Add Doxygen comments for documenting internal and public drivers APIs
* Remove incorrectly grouped Devicekey from the drivers Doxygen
  group and add to the newly created `Device Key` group.

Author: hugueskamba

TESTS/mbed_drivers/timerevent/main.cpp

@@ -21,7 +21,7 @@
 #include "greentea-client/test_env.h"
 #include "unity.h"
 #include "utest.h"
-#include "drivers/TimerEvent.h"
+#include "drivers/internal/TimerEvent.h"
 #include "hal/ticker_api.h"
 #include "rtos.h"
 

UNITTESTS/stubs/SerialBase_stub.cpp

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-#include "SerialBase.h"
+#include "drivers/internal/SerialBase.h"
 
 namespace mbed {
 

drivers/AnalogIn.h

@@ -26,7 +26,13 @@
 #include "platform/PlatformMutex.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api Public API */
+/** @{*/
+/**
+ * \defgroup drivers_AnalogIn AnalogIn class
+ * @{
+ */
 
 /** An analog input, used for reading the voltage on a pin
  *
@@ -48,7 +54,6 @@ namespace mbed {
  *     }
  * }
  * @endcode
- * @ingroup drivers
  */
 class AnalogIn {
 
@@ -111,8 +116,12 @@ class AnalogIn {
     analogin_t _adc;
     static SingletonPtr<PlatformMutex> _mutex;
 #endif //!defined(DOXYGEN_ONLY)
+
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/AnalogOut.h

@@ -25,7 +25,13 @@
 #include "platform/PlatformMutex.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_AnalogOut AnalogOut class
+ * @{
+ */
 
 /** An analog output, used for setting the voltage on a pin
  *
@@ -48,7 +54,6 @@ namespace mbed {
  *     }
  * }
  * @endcode
- * @ingroup drivers
  */
 class AnalogOut {
 
@@ -131,6 +136,9 @@ class AnalogOut {
 #endif //!defined(DOXYGEN_ONLY)
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/BusIn.h

@@ -23,12 +23,17 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_BusIn BusIn class
+ * @{
+ */
 
 /** A digital input bus, used for reading the state of a collection of pins
  *
  * @note Synchronization level: Thread safe
- * @ingroup drivers
  */
 class BusIn : private NonCopyable<BusIn> {
 
@@ -125,6 +130,9 @@ class BusIn : private NonCopyable<BusIn> {
 #endif
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/BusInOut.h

@@ -22,15 +22,20 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_BusInOut BusInOut class
+ * @{
+ */
 
 /** A digital input output bus, used for setting the state of a collection of pins.
  *  Implemented as an array of DigitalInOut pins, the bus can be constructed by any
  *  pins without restriction other than being capable of digital input or output
  *  capabilities
  *
  * @note Synchronization level: Thread safe
- * @ingroup drivers
  */
 class BusInOut : private NonCopyable<BusInOut> {
 
@@ -147,6 +152,9 @@ class BusInOut : private NonCopyable<BusInOut> {
 #endif //!defined(DOXYGEN_ONLY)
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/BusOut.h

@@ -22,10 +22,15 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_BusOut BusOut class
+ * @{
+ */
 
 /** A digital output bus, used for setting the state of a collection of pins
- * @ingroup drivers
  */
 class BusOut : private NonCopyable<BusOut> {
 
@@ -125,6 +130,9 @@ class BusOut : private NonCopyable<BusOut> {
 #endif
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/CAN.h

@@ -27,12 +27,17 @@
 #include "platform/NonCopyable.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_CANMessage CANMessage class
+ * @{
+ */
 
 /** CANMessage class
  *
  * @note Synchronization level: Thread safe
- * @ingroup drivers
  */
 class CANMessage : public CAN_Message {
 
@@ -70,8 +75,14 @@ class CANMessage : public CAN_Message {
     CANMessage(unsigned int _id, CANFormat _format = CANStandard);
 };
 
+/** @}*/
+
+/**
+ * \defgroup drivers_CAN CAN class
+ * @{
+ */
+
 /** A can bus client, used for communicating with can devices
- * @ingroup drivers
  */
 class CAN : private NonCopyable<CAN> {
 
@@ -300,6 +311,9 @@ class CAN : private NonCopyable<CAN> {
 #endif
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/DigitalIn.h

@@ -22,7 +22,13 @@
 #include "hal/gpio_api.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_DigitalIn DigitalIn class
+ * @{
+ */
 
 /** A digital input, used for reading the state of a pin
  *
@@ -46,7 +52,6 @@ namespace mbed {
  *     }
  * }
  * @endcode
- * @ingroup drivers
  */
 class DigitalIn {
 
@@ -122,6 +127,9 @@ class DigitalIn {
 #endif //!defined(DOXYGEN_ONLY)
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/DigitalInOut.h

@@ -22,12 +22,17 @@
 #include "hal/gpio_api.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_DigitalInOut DigitalInOut class
+ * @{
+ */
 
 /** A digital input/output, used for setting or reading a bi-directional pin
  *
  * @note Synchronization level: Interrupt safe
- * @ingroup drivers
  */
 class DigitalInOut {
 
@@ -144,6 +149,9 @@ class DigitalInOut {
 #endif //!defined(DOXYGEN_ONLY)
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/DigitalOut.h

@@ -21,7 +21,13 @@
 #include "hal/gpio_api.h"
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_DigitalOut DigitalOut class
+ * @{
+ */
 
 /** A digital output, used for setting the state of a pin
  *
@@ -41,7 +47,6 @@ namespace mbed {
  *     }
  * }
  * @endcode
- * @ingroup drivers
  */
 class DigitalOut {
 
@@ -138,6 +143,9 @@ class DigitalOut {
 #endif //!defined(DOXYGEN_ONLY)
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/Ethernet.h

@@ -23,7 +23,13 @@
 #if DEVICE_ETHERNET || defined(DOXYGEN_ONLY)
 
 namespace mbed {
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_Ethernet Ethernet class
+ * @{
+ */
 
 /** An ethernet interface, to use with the ethernet pins.
  *
@@ -54,7 +60,6 @@ namespace mbed {
  *     }
  * }
  * @endcode
- * @ingroup drivers
  */
 MBED_DEPRECATED(
     "EthInterface is now the preferred way to get an Ethernet object.",
@@ -175,6 +180,9 @@ class Ethernet : private NonCopyable<Ethernet> {
     void set_link(Mode mode);
 };
 
+/** @}*/
+/** @}*/
+
 } // namespace mbed
 
 #endif

drivers/FlashIAP.h

@@ -49,12 +49,17 @@ extern uint32_t Load$$LR$$LR_IROM1$$Limit[];
 
 namespace mbed {
 
-/** \addtogroup drivers */
+/** \ingroup drivers */
+/** \addtogroup drivers-public-api */
+/** @{*/
+/**
+ * \defgroup drivers_FlashIAP FlashIAP class
+ * @{
+ */
 
 /** Flash IAP driver. It invokes flash HAL functions.
  *
  * @note Synchronization level: Thread safe
- * @ingroup drivers
  */
 class FlashIAP : private NonCopyable<FlashIAP> {
 public:
@@ -181,6 +186,9 @@ class FlashIAP : private NonCopyable<FlashIAP> {
 #endif
 };
 
+/** @}*/
+/** @}*/
+
 } /* namespace mbed */
 
 #endif  /* DEVICE_FLASH */