doxygen documenting

17 files changed, 63 insertions, 79 deletions

diff --git a/tinyusb/class/cdc.h b/tinyusb/class/cdc.h
index aaab2ace9..8253e9c7b 100644
--- a/tinyusb/class/cdc.h
+++ b/tinyusb/class/cdc.h
@@ -36,7 +36,7 @@
 */

 /**************************************************************************/

 

-/** \ingroup ClassDriver Class Driver

+/** \ingroup group_class

  *  \defgroup ClassDriver_CDC Communication Device Class (CDC)

  *            Currently only Abstract Control Model subclass is supported

  *  @{ */

diff --git a/tinyusb/class/custom_class.h b/tinyusb/class/custom_class.h
index 0070e2d53..f1c7bfd90 100644
--- a/tinyusb/class/custom_class.h
+++ b/tinyusb/class/custom_class.h
@@ -36,11 +36,9 @@
 */
 /**************************************************************************/
 
-/** \addtogroup ClassDriver Class Driver
- * @{
+/** \ingroup group_class
  *  \defgroup Group_Custom Custom Class (not supported yet)
- *  @{
- */
+ *  @{ */
 
 #ifndef _TUSB_CUSTOM_CLASS_H_
 #define _TUSB_CUSTOM_CLASS_H_
@@ -88,4 +86,3 @@ void         cush_close(uint8_t dev_addr);
 #endif /* _TUSB_CUSTOM_CLASS_H_ */
 
 /** @} */
-/** @} */
diff --git a/tinyusb/class/hid.h b/tinyusb/class/hid.h
index 91a7ece3b..c95cfa245 100644
--- a/tinyusb/class/hid.h
+++ b/tinyusb/class/hid.h
@@ -36,8 +36,7 @@
 */

 /**************************************************************************/

 

-/** \addtogroup ClassDriver Class Driver

- *  @{

+/** \ingroup group_class

  *  \defgroup ClassDriver_HID Human Interface Device (HID)

  *  @{ */

 

@@ -524,4 +523,3 @@ enum {
 #endif /* _TUSB_HID_H__ */

 

 /// @}

-/// @}

diff --git a/tinyusb/class/msc.h b/tinyusb/class/msc.h
index 0183b3fa3..727dd0382 100644
--- a/tinyusb/class/msc.h
+++ b/tinyusb/class/msc.h
@@ -36,8 +36,7 @@
 */

 /**************************************************************************/

 

-/** \addtogroup ClassDriver Class Driver

- *  @{

+/** \ingroup group_class

  *  \defgroup ClassDriver_MSC MassStorage (MSC)

  *  @{ */

 

@@ -358,4 +357,3 @@ STATIC_ASSERT(sizeof(scsi_write10_t) == 10, "size is not correct");
 

 /// @}

 /// @}

-/// @}

diff --git a/tinyusb/common/std_descriptors.h b/tinyusb/common/std_descriptors.h
index 9c9d06c4d..bf34008e2 100644
--- a/tinyusb/common/std_descriptors.h
+++ b/tinyusb/common/std_descriptors.h
@@ -36,8 +36,7 @@
 */

 /**************************************************************************/

 

-/** \brief Types & Declaration by USB Specs. All documents sources mentioned here (eg section 3.5) is referring to USB 2.0 Specs unless state otherwise

- */

+/// \brief Types & Declaration by USB Specs. All documents sources mentioned here (eg section 3.5) is referring to USB 2.0 Specs unless state otherwise

 

 /** \addtogroup group_usb_definitions USB Definitions

  * @{

diff --git a/tinyusb/doxygen/configuration.h b/tinyusb/doxygen/configuration.txt
index 33a31479f..3821dce8b 100644
--- a/tinyusb/doxygen/configuration.h
+++ b/tinyusb/doxygen/configuration.txt
@@ -18,8 +18,8 @@
  */

 #define TUSB_CFG_ATTR_USBRAM

 

-#define TUSB_CFG_MCU          ///< Select one of the supported MCU, the value must be from \ref config_mcu_selection

-#define TUSB_CFG_OS           ///< Select one of the supported RTOS, the value must be from \ref TUSB_OS RTOS.

+#define TUSB_CFG_MCU          ///< Select one of the supported MCU, the value must be from \ref group_mcu

+#define TUSB_CFG_OS           ///< Select one of the supported RTOS, the value must be from \ref group_supported_os.

 #define TUSB_CFG_OS_TASK_PRIO ///< If \ref TUSB_CFG_OS is configured to use a real RTOS (other than TUSB_OS_NONE). This determines the priority of the usb stack task.

 #define TUSB_CFG_TICKS_HZ     ///< The rate ticks in hert. This is used in conjunction with \ref tusb_tick_get to calculate timing.

 

@@ -60,6 +60,10 @@
 

 #define TUSB_CFG_DEVICE_CONTROL_ENDOINT_SIZE ///< Max packet size of Cotnrol Endpoint, default is 64

 

+/// Application MUST define this variable and initialize its pointers's member to all required USB descriptors including

+/// Device Descriptor, Configuration Descriptor, String Descriptors, HID Report Descriptors etc ...

+tusbd_descriptor_pointer_t tusbd_descriptor_pointers;

+

 /** \defgroup config_device_class Class Driver

  * \brief For each Class Driver a value of 1 means enable, value of 0 mean disable

  * @{ */

@@ -70,6 +74,6 @@
 #define TUSB_CFG_DEVICE_CDC 				 ///< Enable Virtual Serial (Communication Device Class)

 /** @} */

 

- /** @} */ // group Device

+/** @} */ // group Device

 

 /** @} */

diff --git a/tinyusb/doxygen/group_def.txt b/tinyusb/doxygen/group_def.txt
new file mode 100644
index 000000000..cfc59d853
--- /dev/null
+++ b/tinyusb/doxygen/group_def.txt
@@ -0,0 +1,9 @@
+// define all the modules group to have the desired ordering since doxygen order module group by
+// the order of files it is feed
+
+/// \defgroup group_class Application - Class Driver API
+
+/// \defgroup group_application_api Application - Stack API
+/// \brief Non-Class driver API
+
+/// \defgroup group_configuration Configuration tusb_config.h
diff --git a/tinyusb/hal/hal.h b/tinyusb/hal/hal.h
index 8029685f0..650c16eca 100644
--- a/tinyusb/hal/hal.h
+++ b/tinyusb/hal/hal.h
@@ -39,15 +39,6 @@
 #ifndef _TUSB_HAL_H_

 #define _TUSB_HAL_H_

 

-/** \ingroup group_usbd

- * \ingroup group_usbh

- * \defgroup group_hal Hardware Abtract Layer (HAL)

- * Hardware Abstraction Layer (HAL) is an abstraction layer, between the physical hardware and the tinyusb stack.

- * Its function is to hide differences in hardware from most of MCUs, so that most of the stack code does not need to be changed to

- * run on systems with a different MCU.

- * HAL are sets of routines that emulate some platform-specific details, giving programs direct access to the hardware resources.

- *  @{ */

-

 //--------------------------------------------------------------------+

 // INCLUDES

 //--------------------------------------------------------------------+

@@ -56,11 +47,19 @@
 #include "common/tusb_errors.h"

 #include "common/compiler/compiler.h"

 

+// callback from tusb.h

+extern void tusb_isr(uint8_t coreid);

+

 //--------------------------------------------------------------------+

 // HAL API

 //--------------------------------------------------------------------+

-// callback from tusb.h

-extern void tusb_isr(uint8_t coreid);

+/** \ingroup group_mcu

+ * \defgroup group_hal Hardware Abtract Layer (HAL)

+ * Hardware Abstraction Layer (HAL) is an abstraction layer, between the physical hardware and the tinyusb stack.

+ * Its function is to hide differences in hardware from most of MCUs, so that most of the stack code does not need to be changed to

+ * run on systems with a different MCU.

+ * HAL are sets of routines that emulate some platform-specific details, giving programs direct access to the hardware resources.

+ *  @{ */

 

 /** \brief    Initialize USB controller hardware

  * \returns   \ref tusb_error_t type to indicate success or error condition.

diff --git a/tinyusb/hal/hal_lpc11uxx.h b/tinyusb/hal/hal_lpc11uxx.h
index b497d3778..d94aa3dd3 100644
--- a/tinyusb/hal/hal_lpc11uxx.h
+++ b/tinyusb/hal/hal_lpc11uxx.h
@@ -36,10 +36,6 @@
 */

 /**************************************************************************/

 

-/** \ingroup group_hal

- *  \defgroup group_hal_lpc11u LPC11uxx

- *  @{ */

-

 #ifndef _TUSB_HAL_LPC11UXX_H_

 #define _TUSB_HAL_LPC11UXX_H_

 

@@ -66,5 +62,3 @@ static inline void hal_interrupt_disable(uint8_t coreid)
 #endif

 

 #endif /* _TUSB_HAL_LPC11UXX_H_ */

-

-/** @} */

diff --git a/tinyusb/hal/hal_lpc13uxx.h b/tinyusb/hal/hal_lpc13uxx.h
index 552fe6b56..c5dc8afd4 100644
--- a/tinyusb/hal/hal_lpc13uxx.h
+++ b/tinyusb/hal/hal_lpc13uxx.h
@@ -36,10 +36,6 @@
 */

 /**************************************************************************/

 

-/** \ingroup group_hal

- *  \defgroup group_hal_lpc13u LPC13uxx (12-bit ADC)

- *  @{ */

-

 #ifndef _TUSB_HAL_LPC13UXX_H_

 #define _TUSB_HAL_LPC13UXX_H_

 

@@ -67,4 +63,3 @@ static inline void hal_interrupt_disable(uint8_t coreid)
 

 #endif /* _TUSB_HAL_LPC13UXX_H_ */

 

-/** @} */

diff --git a/tinyusb/hal/hal_lpc175x_6x.h b/tinyusb/hal/hal_lpc175x_6x.h
index 47658c6aa..744454110 100644
--- a/tinyusb/hal/hal_lpc175x_6x.h
+++ b/tinyusb/hal/hal_lpc175x_6x.h
@@ -36,10 +36,6 @@
 */
 /**************************************************************************/
 
-/** \ingroup group_hal
- *  \defgroup group_hal_lpc175x_6x LPC175x_6x
- *  @{ */
-
 #ifndef _TUSB_HAL_LPC175X_6X_H_
 #define _TUSB_HAL_LPC175X_6X_H_
 
@@ -53,15 +49,15 @@
 //--------------------------------------------------------------------+
 //
 //--------------------------------------------------------------------+
-static inline void hal_interrupt_enable(uint8_t controller_id)
+static inline void hal_interrupt_enable(uint8_t coreid)
 {
-  (void) controller_id; // discard compiler's warning
+  (void) coreid; // discard compiler's warning
   NVIC_EnableIRQ(USB_IRQn);
 }
 
-static inline void hal_interrupt_disable(uint8_t controller_id)
+static inline void hal_interrupt_disable(uint8_t coreid)
 {
-  (void) controller_id; // discard compiler's warning
+  (void) coreid; // discard compiler's warning
   NVIC_DisableIRQ(USB_IRQn);
 }
 
@@ -71,4 +67,3 @@ static inline void hal_interrupt_disable(uint8_t controller_id)
 
 #endif /* _TUSB_HAL_LPC175X_6X_H_ */
 
-/** @} */
diff --git a/tinyusb/hal/hal_lpc43xx.h b/tinyusb/hal/hal_lpc43xx.h
index 4aafc1e3e..6360384ea 100644
--- a/tinyusb/hal/hal_lpc43xx.h
+++ b/tinyusb/hal/hal_lpc43xx.h
@@ -36,9 +36,6 @@
 */

 /**************************************************************************/

 

-/** \ingroup group_hal

- *  \defgroup group_hal_lpc143xx LPC43xx

- *  @{ */

 #ifndef _TUSB_HAL_LPC43XX_H_

 #define _TUSB_HAL_LPC43XX_H_

 

@@ -64,4 +61,3 @@ static inline void hal_interrupt_disable(uint8_t coreid)
 

 #endif /* _TUSB_HAL_LPC43XX_H_ */

 

-/** @} */

diff --git a/tinyusb/host/hub.h b/tinyusb/host/hub.h
index 6097e15e3..6ecba96f0 100644
--- a/tinyusb/host/hub.h
+++ b/tinyusb/host/hub.h
@@ -36,8 +36,7 @@
 */

 /**************************************************************************/

 

-/** \addtogroup ClassDriver

- *  @{

+/** \ingroup group_class

  *  \defgroup ClassDriver_Hub Hub (Host only)

  *  \details  Like most PC's OS, Hub support is completely hidden from Application. In fact, application cannot determine whether

  *            a device is mounted directly via roothub or via a hub's port. All Hub-related procedures are performed and managed

@@ -209,4 +208,3 @@ void         hub_close(uint8_t dev_addr);
 #endif /* _TUSB_HUB_H_ */

 

 /** @} */

-/** @} */

diff --git a/tinyusb/osal/osal.h b/tinyusb/osal/osal.h
index ca4015a2d..ebbade9d9 100644
--- a/tinyusb/osal/osal.h
+++ b/tinyusb/osal/osal.h
@@ -39,9 +39,15 @@
 #ifndef _TUSB_OSAL_H_

 #define _TUSB_OSAL_H_

 

-/** \ingroup group_configuration

- *  \defgroup TUSB_OS RTOS Integration Selection

- * \brief TUSB_CFG_OS must be defined to one of these

+#ifdef __cplusplus

+ extern "C" {

+#endif

+

+/** \defgroup group_osal OS Abstraction Layer (OSAL)

+ *  @{ */

+

+/** \defgroup group_supported_os Supported RTOS

+ * \brief \ref TUSB_CFG_OS must be defined to one of these

  *  @{ */

 #define TUSB_OS_NONE       1 ///< No RTOS is used

 #define TUSB_OS_FREERTOS   2 ///< FreeRTOS is used

@@ -49,14 +55,6 @@
 #define TUSB_OS_UCOS3      4 ///< MicroC OS III is used (not supported yet)

 /** @} */

 

-

-/** \defgroup group_osal OS Abstraction Layer (OSAL)

- *  @{ */

-

-#ifdef __cplusplus

- extern "C" {

-#endif

-

 #include "tusb_option.h"

 

 #ifndef _TEST_

diff --git a/tinyusb/tusb.c b/tinyusb/tusb.c
index 8a0d1be59..15aa1fae9 100644
--- a/tinyusb/tusb.c
+++ b/tinyusb/tusb.c
@@ -63,15 +63,19 @@ tusb_error_t tusb_init(void)
   return TUSB_ERROR_NONE;

 }

 

-// called from hal layer

-void tusb_isr(uint8_t controller_id)

+/** \ingroup group_application_api

+ * \brief USB interrupt handler

+ * \param[in]  coreid Controller ID where the interrupt happened

+ * \note This function must be called by HAL layer or Application for the stack to manage USB events/transfers.

+ */

+void tusb_isr(uint8_t coreid)

 {

 #if MODE_HOST_SUPPORTED

-  hcd_isr(controller_id);

+  hcd_isr(coreid);

 #endif

 

 #if MODE_DEVICE_SUPPORTED

-  dcd_isr(controller_id);

+  dcd_isr(coreid);

 #endif

 

 }

diff --git a/tinyusb/tusb.h b/tinyusb/tusb.h
index 2d40c1fec..606803ae0 100644
--- a/tinyusb/tusb.h
+++ b/tinyusb/tusb.h
@@ -93,7 +93,7 @@
 //--------------------------------------------------------------------+

 // APPLICATION API

 //--------------------------------------------------------------------+

-/** \defgroup application_setup Application Setup

+/** \ingroup group_application_api

  *  @{ */

 

 /** \brief Initialize the usb stack

diff --git a/tinyusb/tusb_option.h b/tinyusb/tusb_option.h
index 467abf397..0cfb4ae4a 100644
--- a/tinyusb/tusb_option.h
+++ b/tinyusb/tusb_option.h
@@ -45,18 +45,15 @@
 #define TUSB_VERSION_NAME   "alpha"

 #define TUSB_VERSION        XSTRING_(TUSB_VERSION_YEAR) "." XSTRING_(TUSB_VERSION_MONTH)

 

-/** \defgroup group_configuration Configuration tusb_config.h

- *  @{ */

-

-/** \defgroup config_mcu_selection MCU Selection

- * \brief TUSB_CFG_MCU must be defined to one of these

+/** \defgroup group_mcu Supported MCU

+ * \ref TUSB_CFG_MCU must be defined to one of these

  *  @{ */

 #define MCU_LPC13UXX       1 ///< NXP LPC13xx 12 bit ADC family with USB on-chip Rom Driver (not supported yet)

-#define MCU_LPC13XX        2 ///< NXP LPC13xx 10 bit ADC family (not supported yet)

-#define MCU_LPC11UXX       3 ///< NXP LPC11Uxx family (not supported yet)

+#define MCU_LPC13XX        2 ///< NXP LPC13xx 10 bit ADC family

+#define MCU_LPC11UXX       3 ///< NXP LPC11Uxx family

 #define MCU_LPC43XX        4 ///< NXP LPC43xx family

 #define MCU_LPC18XX        5 ///< NXP LPC18xx family (not supported yet)

-#define MCU_LPC175X_6X     6 ///< NXP LPC175x, LPC176x family (not supported yet)

+#define MCU_LPC175X_6X     6 ///< NXP LPC175x, LPC176x family

 #define MCU_LPC177X_8X     7 ///< NXP LPC177x, LPC178x family (not supported yet)

 /** @} */

 

@@ -68,6 +65,9 @@
 

 #include TUSB_CFG_CONFIG_FILE

 

+/** \ingroup group_configuration

+ *  @{ */

+

 //--------------------------------------------------------------------+

 // CONTROLLER

 //--------------------------------------------------------------------+