嵌入式C语言中的Doxygen注释模板

 嵌入式C语言开发中通常使用Doxygen进行文档的生成。Doxygen支持多种格式，非常灵活，但排版不好就会显的比较杂乱，不便于阅读。下面给出一份注释模板。

一、文件注释，放于文件的开头

[cpp] view plaincopy

1. /** 
2. * @file         filename 
3. * @brief        This is a brief description. 
4. * @details  This is the detail description. 
5. * @author       author 
6. * @date     date 
7. * @version  A001 
8. * @par Copyright (c):  
9. *       XXX公司 
10. * @par History:          
11. *   version: author, date, desc\n 
12. */  

二、函数注释，放于函数声明前

[cpp] view plaincopy

1. /** 
2.  * This is a brief description. 
3.  * This is a detail description. 
4.  * @param[in]   inArgName input argument description. 
5.  * @param[out]  outArgName output argument description.  
6.  * @retval  OK  成功 
7.  * @retval  ERROR   错误  
8.  * @par 标识符 
9.  *      保留 
10.  * @par 其它 
11.  *      无 
12.  * @par 修改日志 
13.  *      XXX于201X-XX-XX创建 
14.  */  

三、数据结构注释，放于数据结构定义前

[cpp] view plaincopy

1. /** 
2.  * The brief description. 
3.  * The detail description. 
4.  */  
5. typedef struct  
6. {  
7.     int var1;///<Description of the member variable  
8. }XXXX;  

四、宏定义注释，放于宏定义上方或者右侧

[html] view plaincopy

1. /** Description of the macro */  
2. #define XXXX_XXX_XX     0  

或者

[html] view plaincopy

1. #define XXXX_XXX_XX     0 ///< Description of the macro.  

五、全局和静态变量注释

[cpp] view plaincopy

1. /**  Description of global variable  */  
2. int g_xxx = 0;  
3.   
4. static int s_xxx = 0; ///<  Description of static variable  

====================================

其他参考：

http://fnch.users.sourceforge.net/doxygen_c.html

output ：http://fnch.users.sourceforge.net/data/doxygen_c/html/doxygen__c_8h.html