注释格式

1. 注释例子
1.1 注释一个宏

/**
  @def MAX(x,y)
  Computes the maximum of \a x and \a y.
*/
#define MAX(x,y) ((x)>(y)?(x):(y))
或者：
/**
   Computes the absolute value of its argument \a x.
*/
#define ABS(x) (((x)>0)?(x):-(x))

其中：
    @a：表示引用的是一个变量，会用斜体字显示.

1.2 注释一个枚举
/**
 * @enum my_enum
 * enum for test.
 */
enum my_enum {
    var1,   /**< first. */
    var2,   /**< second. */
    var3    /**< third. */
};

1.3 注释一个union
/**
 * @union my_union
 * This union is used for xxxx.
 */
union my_union {
    int choice1;            /**< first desc */
    unsigned long choice2;  /**< second desc */
    unsigned char *choice3; /**< third desc */
};

1.4 注释一个结构体
/**
 * @struct my_struct
 * This struct used for xxxx.
 */
struct my_struct {
    int a;              /**< first */
    enum my_enum b;     /**< second. @see enum my_enum */
    union my_union c;   /**< third. @see union my_union */

};

1.5 注释一个类型定义
/**
 * @typedef my_type
 * This type is used for xxxx.
 */
typedef unsigned long long int my_type;

1.6 注释一个函数
/** @fn int print_sth(int times, struct my_struct *ms)
 *  @brief print function.
 *  @details
 *      print function for struct my_struct.
 *      @see struct my_struct
 *  @param times print times.
 *  @param ms info source.
 *  @note note information.
 *  @warning warning information.
 *  @return -1 on fail while 0 on success.
 */

1.7 注释文件头
/**
 * @file      file name
 * @version   1.0.0
 * @date      2011-10-10
 * @author    Shulong Li
 * @brief
 *      This is brief,
 *      Yes a brief description.
 * @details
 *      This is detail,
 *      Yes a detailed description.
 * @bug
 *      Known bugs.
 * @warning
 *      warning information
 * @copyright
 *      GNU Public License.
 */