例子注释建议遵守Doxygen规范

amine 2012-05-17

展开全文

主要用到的Doxygen一些编码规范：

1.ANSI standard data types defined in the ANSI C header file <stdint.h> are used. Doxygend编码规范

stdint.h中，常用的数据类型如下：

typedef   signed             char  int8_t;
typedef   signed short       int   int16_t;
typedef   signed             int   int32_t;
typedef   signed           __int64 int64_t;
typedef   unsigned           char  uint8_t;
typedef   unsigned short     int   uint16_t;
typedef   unsigned           int   uint32_t;
typedef   unsigned         __int64 uint64_t;

2.#define constants that include expressions must be enclosed by parenthesis.

例如：

/** SSP data size select, must be 4 bits to 16 bits */
#define SSP_CR0_DSS(n)                  ((uint32_t)((n-1)&0xF))

3.推荐使用Doxygen comments

Doxygen comments 格式有多种，推荐使用以下方式

1) 代码块以及函数注释

Function Comments provide for each function the following information:

brief function overview.
detailed parameter explanation
detailed information about return values

Doxygen Example

/*************************************************************************//**
 * @brief     Send a block of data via SPI 
 * @param[in] wbuf  Pointer to Transmit buffer
 * @param[in] rlen  Length of Transmit buffer
 * @return    Number of data sent
*****************************************************************************/

2) 对于宏定义和结构成员的注释

如果注释和定义在同一行，用 /*!< xxxx */

int  var;  /*!<  Detailed  description  after  the  member  */

如果不在同一行，用/** xxx */

/** EXTI Event Mode Definition */
typedef enum {
  COX_EXTI_NONE                = 0,  /*!< None interrupt */
  COX_EXTI_EDGE_RISING         = 1,  /*!< Rising edge interrupt */
  COX_EXTI_EDGE_FALLING        = 2,  /*!< Falling edge interrupt */
  COX_EXTI_EDGE_RISING_FALLING = 3,  /*!< Both edge interrupt (Rising and Falling) */
  COX_EXTI_LEVEL_HIGH          = 4,  /*!< Hign Level interrupt */
  COX_EXTI_LEVEL_LOW           = 5,  /*!< Low Level interrupt */  
} EXTI_EVENT_Def;