[总结]doxygen的使用与C/C++注释规范
2014-04-11 11:27 setsail_wu 阅读(4087) 评论(0) 编辑 收藏 举报近期由于项目需要，参考网上资料整理了一下注释规范，详细内容如下：
1. doxygen的安装与参数配置
1.1. 安装
$ sudo apt-get install doxygen
以下可以选择安装
$sudo apt-get install doxygen-doc doxygen-gui graphviztexpower dot2tex graphviz-doc texpower-examples
1.2. 生成配置文件
在 shell 提示上，输入命令 doxygen -g。这个命令在当前目录中生成一个可编辑的配置文件 Doxyfile。可以改变这个文件名，在这种情况下，应该调用 doxygen -g<user-specified file name>
1.3. 修改配置参数
l <OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。
l <INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。例如，请考虑以下代码片段：
INPUT = /home/user1/project/kernel /home/user1/project/memory
在这里，doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把<RECURSIVE> 标记设置为 Yes。
l <FILE_PATTERNS>：在默认情况下，doxygen会搜索具有典型 C/C++ 扩展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果<FILE_PATTERNS> 标记没有相关联的值，doxygen就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用 .c86 作为 C 文件扩展名，就应该在 <FILE_PATTERNS> 标记中添加这个扩展名。
l <RECURSIVE>：如果源代码层次结构是嵌套的，而且需要为所有层次上的 C/C++ 文件生成文档，就把这个标记设置为 Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有/home/user1/project/kernel/vmm 和/home/user1/project/kernel/asm 等子目录。如果这个标记设置为 Yes，doxygen 就会递归地搜索整个层次结构并提取信息。
l <EXTRACT_ALL>：这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为 Yes。
l <EXTRACT_PRIVATE>：把这个标记设置为 Yes。否则，文档不包含类的私有数据成员。
l <EXTRACT_STATIC>：把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。
l <SOURCE_BROWSER>：把这个标记设置为 Yes，自动加入源码。
2. 文件注释
2.1. 示例
/**
* @file apply.c
* @author lishujie
* @version 1.0
* @date 2013-12-12
* @brief this brief
* @details this's details
*/
2.2. 说明
l “@file”后的文件名需与当前文件名一致
3. 结构体注释
3.1. 简洁样例
typedef struct Mac_Config /// the brief structcomment
{
charmacaddr[QCT_OTHER_MACADDR_64]; ///< The brief mement comment
chardevicename[QCT_OTHER_DEVNAME_64]; ///< The brief mement comment
intchecked; ///< The brief mement comment
} Mac_list;
3.2. 详细样例
/**
* this is details struct
*/
typedef struct DynamicConfigT /// The brief mementcomment
{
int nApplyId; ///< The brief mement comment
int nTime; ///< The brief mement comment
int nReboot; ///< The brief mement comment
/** this is details mement comment */
char** aValTable; ///< The brief mement comment
LocalHndl pfnHndl; ///< The brief mement comment
} DynamicConfig;
3.3. 说明
l “///”与注释间留有2个空格
l “///<”与注释间留有1个空格
l 结构体成员的详细注释写在该成员上面
l 结构体成员的详细注释与上一成员间留1个空行
l 推荐结构体使用typedef类型定义
l 推荐使用简洁的结构体注释
4. 枚举注释
4.1. 样例
typedef enum _COLOR /// The brief enum comment
{
BLACK, ///< The brief member comment
NAVY, ///< The brief member comment
}COLOR;
4.2. 说明
l 与结构体的简洁注释相同
5. 宏注释
5.1. 简洁样例
/// This macro is toolong, so comment here briefly!
#define HTTP_REQUEST_LEN_MAX APPLY_BUF_SIZE_BIG
5.2. 详细样例
/**
* The detail macro comment, may be multi-line.
* @param a The brief parameter comment
* @param b The brief parameter comment
* @return The brief return value comment
*/
#define MAX(a, b) ((a) > (b))? (a) : (b)
5.3. 说明
l 尽量少写宏函数，可以使用内联函数代替
l 推荐使用简洁的宏注释
6. 函数注释
6.1. 简洁样例
/// The brieffunction comment, may be multi-line.
static int apply_login();
6.2. 详细样例
/**
* The detail function comment, may bemulti-line.
* @param cur_id The brief parameter comment
* @return The brief return value comment
* @brief The brief function comment
*/
static int reboot_enable( intcur_id )
6.3. 说明
l 简述以///+空格开头或使用@brief，详述以/**开头
l 无参无返回值的简单函数使用简洁注释
l 头文件有声明的函数注释在头文件中；否则注释在代码文件中
7. 其它注释
l 代码中其余注释一律使用普通的单行注释“//”和多行注释“/*”“*/”。
8. 附录
8.1. 注释换行
Doxygen 会忽略你注释中的换行符，将多行注释连接成一个连续行并使用空格隔开。如
果你希望保留两行注释之间的换行，需要在该行末加入“\n”。
8.2. 常用命令
|
命令 |
生成字段名 |
说明 |
|
@attention |
注意 |
|
|
@author |
作者 |
|
|
@bug |
缺陷 |
链接到所有缺陷汇总的缺陷列表 |
|
@brief |
简要注释 |
|
|
@code |
|
代码块开始，与“nendcode”成对使用 |
|
@details |
详细注释 |
|
|
@date |
日期 |
|
|
@endcode |
|
代码块结束，与“ncode”成对使用 |
|
@file |
< 文件名> 文件参考 |
用在文件注释中 |
|
@param |
参数 |
用在函数注释中 |
|
@return |
返回 |
用在函数注释中 |
|
@todo |
TODO |
链接到所有TODO 汇总的TODO 列表 |
|
@version |
版本 |
|
|
@warning |
警告 |
|
8.3. vim+Doxygen方便的写注释
8.3.1. 安装
下载 doxygen的 vim 插件
http://www.vim.org/scripts/script.php?script_id=987
将下载的插件安装到$VIMRUNTIME/plugin目录下
在VIM的配置文件中(windows下的_vimrc，linux下的vimrc或者~/.vimrc)为doxygentoolkit这个插件配置一些全局变量：
let g:doxygenToolkit_authorName="your name"
let g:doxygenToolkit_briefTag_funcName="yes"
8.3.2. 常用命令
Dox
DoxAuthor
DoxLic
8.4. 给source insight添加doxygen注释风格
请参考：http://blog.csdn.net/dayong419/article/details/7932467
参考资料如下：
学习用 doxygen 生成源码文档
http://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/#list2
CommentManual.pdf
https://www.google.com.hk/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&ved=0CCsQFjAA&url=%68%74%74%70%3a%2f%2f%67%65%74%69%6d%61%67%65%2e%67%6f%6f%67%6c%65%63%6f%64%65%2e%63%6f%6d%2f%66%69%6c%65%73%2f%43%6f%6d%6d%65%6e%74%4d%61%6e%75%61%6c%2e%70%64%66&ei=SF5HU66EPZe58gWl7IDIBA&usg=AFQjCNGATKOIt_-gTeszmuke-R7KbNCScQ
