doxygen documenting

2014-03-25 13:00:37 +07:00
parent 41610af72a
commit 15d0139bc5
30 changed files with 184 additions and 243 deletions
--- 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
 *  @{ */
--- 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_ */

 /** @} */
-/** @} */
--- 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__ */

 /// @}
-/// @}
--- 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");

 /// @}
 /// @}
-/// @}
--- 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
 * @{
--- a/tinyusb/doxygen/configuration.txt
+++ 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

 /** @} */
--- a/tinyusb/doxygen/group_def.txt
+++ 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
--- 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.
--- 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_ */
-
-/** @} */
--- 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_ */

-/** @} */
--- 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_ */

-/** @} */
--- 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_ */

-/** @} */
--- 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_ */

 /** @} */
-/** @} */
--- 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_
--- 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

 }
--- 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
--- 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
 //--------------------------------------------------------------------+