doxygen documenting

2014-03-25 13:00:37 +07:00
parent 41610af72a
commit 15d0139bc5
30 changed files with 184 additions and 243 deletions
--- a/boards/ansi_escape.h
+++ b/boards/ansi_escape.h
@@ -36,18 +36,9 @@
 */
 /**************************************************************************/

-/** \file
- *  \brief TBD
- *
- *  \note TBD
- */
-
-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
+/** \ingroup group_board
+ *  \defgroup group_ansi_esc ANSI Esacpe Code
+ *  @{ */

 #ifndef _TUSB_ANSI_ESC_CODE_H_
 #define _TUSB_ANSI_ESC_CODE_H_
@@ -61,21 +52,29 @@
 #define CSI_SGR(x)      CSI_CODE(#x) "m"

 //------------- Cursor movement -------------//
-#define ANSI_CURSOR_UP(n)        CSI_CODE(#n "A")
-#define ANSI_CURSOR_DOWN(n)      CSI_CODE(#n "B")
-#define ANSI_CURSOR_FORWARD(n)   CSI_CODE(#n "C")
-#define ANSI_CURSOR_BACKWARD(n)  CSI_CODE(#n "D")
-#define ANSI_CURSOR_LINE_DOWN(n) CSI_CODE(#n "E")
-#define ANSI_CURSOR_LINE_UP(n)   CSI_CODE(#n "F")
-#define ANSI_CURSOR_POSITION(n, m) CSI_CODE(#n ";" #m "H")
+/** \defgroup group_ansi_cursor Cursor Movement
+ *  @{ */
+#define ANSI_CURSOR_UP(n)        CSI_CODE(#n "A")          ///< Move cursor up
+#define ANSI_CURSOR_DOWN(n)      CSI_CODE(#n "B")          ///< Move cursor down
+#define ANSI_CURSOR_FORWARD(n)   CSI_CODE(#n "C")          ///< Move cursor forward
+#define ANSI_CURSOR_BACKWARD(n)  CSI_CODE(#n "D")          ///< Move cursor backward
+#define ANSI_CURSOR_LINE_DOWN(n) CSI_CODE(#n "E")          ///< Move cursor to the beginning of the line (n) down
+#define ANSI_CURSOR_LINE_UP(n)   CSI_CODE(#n "F")          ///< Move cursor to the beginning of the line (n) up
+#define ANSI_CURSOR_POSITION(n, m) CSI_CODE(#n ";" #m "H") ///< Move cursor to position (n, m)
+/** @} */

-#define ANSI_ERASE_SCREEN(n)     CSI_CODE(#n "J")
-#define ANSI_ERASE_LINE(n)       CSI_CODE(#n "K")
+//------------- Screen -------------//
+/** \defgroup group_ansi_screen Screen Control
+ *  @{ */
+#define ANSI_ERASE_SCREEN(n)     CSI_CODE(#n "J") ///< Erase the screen
+#define ANSI_ERASE_LINE(n)       CSI_CODE(#n "K") ///< Erase the line (n)
+#define ANSI_SCROLL_UP(n)        CSI_CODE(#n "S") ///< Scroll the whole page up (n) lines
+#define ANSI_SCROLL_DOWN(n)      CSI_CODE(#n "T") ///< Scroll the whole page down (n) lines
+/** @} */

-#define ANSI_SCROLL_UP(n)        CSI_CODE(#n "S")
-#define ANSI_SCROLL_DOWN(n)      CSI_CODE(#n "T")
-
-/** text color */
+//------------- Text Color -------------//
+/** \defgroup group_ansi_text Text Color
+ *  @{ */
 #define ANSI_TEXT_BLACK          CSI_SGR(30)
 #define ANSI_TEXT_RED            CSI_SGR(31)
 #define ANSI_TEXT_GREEN          CSI_SGR(32)
@@ -85,8 +84,11 @@
 #define ANSI_TEXT_CYAN           CSI_SGR(36)
 #define ANSI_TEXT_WHITE          CSI_SGR(37)
 #define ANSI_TEXT_DEFAULT        CSI_SGR(39)
+/** @} */

-/** background color */
+//------------- Background Color -------------//
+/** \defgroup group_ansi_background Background Color
+ *  @{ */
 #define ANSI_BG_BLACK            CSI_SGR(40)
 #define ANSI_BG_RED              CSI_SGR(41)
 #define ANSI_BG_GREEN            CSI_SGR(42)
@@ -96,6 +98,7 @@
 #define ANSI_BG_CYAN             CSI_SGR(46)
 #define ANSI_BG_WHITE            CSI_SGR(47)
 #define ANSI_BG_DEFAULT          CSI_SGR(49)
+/** @} */

 #ifdef __cplusplus
 }
--- a/boards/board.h
+++ b/boards/board.h
@@ -36,12 +36,8 @@
 */
 /**************************************************************************/

-/**
- *  \defgroup Group_Board Boards
- *  \brief TBD
- *
- *  @{
- */
+/** \defgroup group_board Boards Abstraction Layer
+ *  @{ */

 #ifndef _TUSB_BOARD_H_
 #define _TUSB_BOARD_H_
@@ -59,28 +55,38 @@
 //--------------------------------------------------------------------+
 // BOARD DEFINE
 //--------------------------------------------------------------------+
-#define BOARD_RF1GHZNODE            1100
-#define BOARD_LPCXPRESSO1347        1300
-#define BOARD_LPCXPRESSO1769        1700
+/** \defgroup group_supported_board Supported Boards
+ *  @{ */
+#define BOARD_RF1GHZNODE            1100 ///< LPC11U37 from microbuilder http://www.microbuilder.eu/Blog/13-03-14/LPC1xxx_1GHZ_Wireless_Board_Preview.aspx
+#define BOARD_LPCXPRESSO1347        1300 ///< LPCXpresso 1347, some APIs requires the base board
+#define BOARD_LPCXPRESSO1769        1700 ///< LPCXpresso 1769, some APIs requires the base board

-#define BOARD_NGX4330               4300
-#define BOARD_EA4357                4301
-#define BOARD_MCB4300               4302
-#define BOARD_HITEX4350             4303
+#define BOARD_NGX4330               4300 ///< NGX 4330 Xplorer
+#define BOARD_EA4357                4301 ///< Embedded Artists LPC4357 developer kit
+#define BOARD_MCB4300               4302 ///< Keil MCB4300
+#define BOARD_HITEX4350             4303 ///< Hitex 4350
 #define BOARD_LPC4357USB            4304

-#define BOARD_LPCLINK2              4370
+#define BOARD_LPCLINK2              4370 ///< LPClink2 uses as LPC4370 development board
+/** @} */

 //--------------------------------------------------------------------+
 // PRINTF TARGET DEFINE
 //--------------------------------------------------------------------+
-#define PRINTF_TARGET_SEMIHOST      1
-#define PRINTF_TARGET_UART          2
-#define PRINTF_TARGET_SWO           3 // aka SWV, ITM
-#define PRINTF_TARGET_NONE          4
+/** \defgroup group_printf Printf Retarget
+ * \brief Retarget the standard stdio printf/getchar to other IOs
+ *  @{ */
+#define PRINTF_TARGET_SEMIHOST      1 ///< Using the semihost support from toolchain, requires no hardware but is the slowest
+#define PRINTF_TARGET_UART          2 ///< Using UART as stdio, this is the default for most of the board
+#define PRINTF_TARGET_SWO           3 ///< Using non-instructive serial wire output (SWO), is the best option since it does not slow down MCU but requires supported from debugger and IDE
+#define PRINTF_TARGET_NONE          4 ///< Using none at all.
+/** @} */

 #define PRINTF(...) printf(__VA_ARGS__)

+//--------------------------------------------------------------------+
+// BOARD INCLUDE
+//--------------------------------------------------------------------+
 #if BOARD == BOARD_NGX4330
  #include "ngx/board_ngx4330.h"
 #elif BOARD == BOARD_LPCXPRESSO1347
@@ -106,24 +112,52 @@
 //--------------------------------------------------------------------+
 // Common Configuration
 //--------------------------------------------------------------------+
-#define CFG_UART_BAUDRATE    115200
+#define CFG_UART_BAUDRATE    115200 ///< Baudrate for UART

 //--------------------------------------------------------------------+
 // Board Common API
 //--------------------------------------------------------------------+
-// Init board peripherals : Clock, UART, LEDs, Buttons
+/** \defgroup group_board_api Board API
+ * \brief All the board must support these APIs.
+ *  @{ */
+
+/// Initialize all required peripherals on board including uart, led, buttons etc ...
 void board_init(void);

+/** \brief Turns on and off leds on the board
+ * \param[in]  on_mask  Bitmask for LED's numbers is turning ON
+ * \param[out] off_mask Bitmask for LED's numbers is turning OFF
+ * \note the \a on_mask is more priority then \a off_mask, if an led's number is present on both.
+ * It will be turned ON.
+ */
 void board_leds(uint32_t on_mask, uint32_t off_mask);
+
+/** \brief Get the current state of the buttons on the board
+ * \return Bitmask where a '1' means active (pressed), a '0' means inactive.
+ */
 uint32_t board_buttons(void);

+/** \brief Get a character input from UART
+ * \return ASCII code of the input character or zero if none.
+ */
 uint8_t  board_uart_getchar(void);
+
+/** \brief Send a character to UART
+ * \param[in]  c the character to be sent
+ */
 void board_uart_putchar(uint8_t c);

+/** @} */
+
 //------------- Board Application  -------------//
 OSAL_TASK_FUNCTION( led_blinking_task , p_task_para);

+/// Initialize the LED blinking task application. The initial blinking rate is 1 Hert (1 per second)
 void led_blinking_init(void);
+
+/** \brief Change the blinking rate.
+ * \param[in]  ms The interval between on and off.
+ */
 void led_blinking_set_interval(uint32_t ms);

 #ifdef __cplusplus
--- a/boards/embedded_artists/ea4357/board_ea4357.h
+++ b/boards/embedded_artists/ea4357/board_ea4357.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_EA4357_H_
 #define _TUSB_BOARD_EA4357_H_

@@ -70,5 +63,3 @@
 #endif

 #endif /* _TUSB_BOARD_EA4357_H_ */
-
-/** @} */
--- a/boards/hitex/board_hitex4350.h
+++ b/boards/hitex/board_hitex4350.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_HITEX4350_H_
 #define _TUSB_BOARD_HITEX4350_H_

@@ -63,5 +56,3 @@
 #endif

 #endif /* _TUSB_BOARD_HITEX4350_H_ */
-
-/** @} */
--- a/boards/keil/board_mcb4300.h
+++ b/boards/keil/board_mcb4300.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_MCB4300_H_
 #define _TUSB_BOARD_MCB4300_H_

@@ -64,5 +57,3 @@
 #endif

 #endif /* _TUSB_BOARD_MCB4300_H_ */
-
-/** @} */
--- a/boards/lpcxpresso/board_lpclink2.h
+++ b/boards/lpcxpresso/board_lpclink2.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_LPCLINK2_H_
 #define _TUSB_BOARD_LPCLINK2_H_

@@ -64,5 +57,3 @@
 #endif

 #endif /* _TUSB_BOARD_LPCLINK2_H_ */
-
-/** @} */
--- a/boards/lpcxpresso/board_lpcxpresso1347.h
+++ b/boards/lpcxpresso/board_lpcxpresso1347.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_LPCXPRESSO1347_H_
 #define _TUSB_BOARD_LPCXPRESSO1347_H_

@@ -61,5 +54,3 @@
 #endif

 #endif /* _TUSB_BOARD_LPCXPRESSO1347_H_ */
-
-/** @} */
--- a/boards/lpcxpresso/board_lpcxpresso1769.h
+++ b/boards/lpcxpresso/board_lpcxpresso1769.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_LPCXPRESSO1769_H_
 #define _TUSB_BOARD_LPCXPRESSO1769_H_

@@ -66,5 +59,3 @@
 #endif

 #endif /* _TUSB_BOARD_LPCXPRESSO1769_H_ */
-
-/** @} */
--- a/boards/microbuilder/board_lpc4357usb.h
+++ b/boards/microbuilder/board_lpc4357usb.h
@@ -36,19 +36,6 @@
 */
 /**************************************************************************/

-/** \file
- *  \brief TBD
- *
- *  \note TBD
- */
-
-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_LPC4357USB_H_
 #define _TUSB_BOARD_LPC4357USB_H_

@@ -71,5 +58,3 @@
 #endif

 #endif /* _TUSB_BOARD_LPC4357USB_H_ */
-
-/** @} */
--- a/boards/microbuilder/board_rf1ghznode.h
+++ b/boards/microbuilder/board_rf1ghznode.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_RF1GHZNODE_H_
 #define _TUSB_BOARD_RF1GHZNODE_H_

@@ -62,5 +55,3 @@
 #endif

 #endif /* _TUSB_BOARD_RF1GHZNODE_H_ */
-
-/** @} */
--- a/boards/ngx/board_ngx4330.h
+++ b/boards/ngx/board_ngx4330.h
@@ -36,13 +36,6 @@
 */
 /**************************************************************************/

-/** \ingroup TBD
- *  \defgroup TBD
- *  \brief TBD
- *
- *  @{
- */
-
 #ifndef _TUSB_BOARD_NGX4330_H_
 #define _TUSB_BOARD_NGX4330_H_

@@ -64,5 +57,3 @@
 #endif

 #endif /* _TUSB_BOARD_NGX4330_H_ */
-
-/** @} */