doxygen笔记2-常用的doxygen约定注释格式的模板

  整篇用来收集各种常用的doxygen约定注释格式的模板。方便实战时使用，大部分实例来自拷贝网络的实例。

1.      文件注释

/**************************************************************************/
 /**
* @brief 对于文件的简单注释
* @details 对于文件的详细注释
* @addtogroup example 范例
* @author Alex.shi
* @version 0.01
* @date 2010/05/25
******************************************************************************
* Copyright (c), 2010, Alex Co., Ltd.
******************************************************************************
* Edit History /n
* -------------------------------------------------------------------------/n
* DATE NAME DESCRIPTION /n
* 2010/05/25 Alex.shi Create./n
******************************************************************************
* @{
*****************************************************************************/
……………… // 源码内容
 
……………… // 源码内容
 
 /** @}***********************************************************/
 

 

modules：

/** \addtogroup <label> 
 *  @{
 */
...

/** @}*/

 

        注意：上面的几处 ”/n” 是必须的，否则显示出来将会把那几行挤到一行中。

 

2. 函数注释

/**
* 设置日期的显存
* @param[in] beginPos 对应区域开始显示的地址
* @param[in] order order>0: year/month/date;order=0: date/month/year
* @param[in] linkChar 日期间的连接符, 目前仅支持 '*''#''-''_''='
* @param[in] year 1-9999
* @param[in] month 1-12
* @param[in] day 1-31
* @return 操作结果, 见 ERR_LED_E
* @note 只有在调用 LED_Update 后才起效
* @see ::LED_Update ::LED_SetSerialBuf ::LED_SetCharBuf
* @see ::LED_SetTimeBuf ::LED_SetMoneyBuf ::LED_ClearAreaBuf
*/
 
PUBLIC ERR_LED_E LED_SetDateBuf(uint8 beginPos, uint8 order, uint8 linkChar,
uint16 year, uint8 month, uint8 day)

说明：

@param：注释输入/输出参数；

@return：返回值

@see：参考内容，若 LED_Update() 函数存在的话，将会在文档中显示为 LED_Update的链接。

@note：显示注意事项

3. 普通注释

/** 区域类型 */
 typedef enum
{
LED_AREA_NULL = 0, /**< 区域头 */
LED_AREA_SERIAL_NO, /**< 序号区域 */
LED_AREA_TEXT, /**< 文本区域 */
LED_AREA_TIME, /**< 时间区域 */
LED_AREA_MONEY, /**< 金额区域 */
LED_AREA_UNDEFINE /**< 区域尾 */
}LED_AREA_E;

说明：

/** 注释内容 */ ：对该注释后面的内容（如枚举类型、变量等）进行注释；

/**< 区域头 */ ：对该注释前面的内容（如枚举类型、变量等）进行注释；

4. 块定义

块定义主要是将相关的一些变量、函数等信息统一在一起显示，并给他们取个名字。如底下的例子，将程序涉及到的几种图标用宏定义出来，并放在一起，起名为“各种图标定义”。

/****************************************************************/
 /**
* @name 各种图标定义
* @{
*/
 
 /** 锁图标 */
#define LED_ICON_LOCK 0x0001
 
 /** 日图标 */
#define LED_ICON_DAY 0x0002
 
 /** 月图标 */
#define LED_ICON_MONTH 0x0004
 ……
 

/** @}各种图标定义**************************************************/
 

 

目前用的比较多的也就是这几种注释格式了，以后有碰到其他的再续。