1. 使用doxygen生成文档的说明;
2. 下载doxygen的二进制文件(下载源码自己编译太麻烦,这里直接下载bin二进制文件);参考http://www.stack.nl/~dimitri/doxygen/manual/install.html。
3. 执行“./configure” 生成makefile文件;执行“make install”安装doxygen;
4. 使用“doxygen -g <cfg-file-name>”生成配置文件,如果不指定名称,默认Doxyfile, 指定"-s"选项的话,可以生成无注释的配置文件;
可以阅读Doxyfile文件中的各个选项设置自己所需配置。这里提供一部分修改配置文件中的选项:一些设置如下:
############配置文件的部分内容#############
# 项目名称,将作为于所生成的程序文档首页标题
PROJECT_NAME = "Test"
# 文档版本号,可对应于项目版本号,譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER = "1.0.0"
# 程序文档输出目录
OUTPUT_DIRECTORY = ./out/
# 程序文档语言环境
OUTPUT_LANGUAGE = Englist
# 如果是制作 C 程序文档,该选项必须设为 YES,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型,只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = YES
# 在 C++ 程序文档中,该值可以设置为 NO,而在 C 程序文档中,由于 C 语言没有所谓的域/名字空间这样的概念,所以此处设置为 YES
HIDE_SCOPE_NAMES = YES
# 让 doxygen 静悄悄地为你生成文档,只有出现警告或错误时,才在终端输出提示信息
QUIET = YES
# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS = *.h
# 递归遍历当前目录的子目录,寻找被文档化的程序源文件
RECURSIVE = YES
# 示例程序目录
EXAMPLE_PATH = example/
# 示例程序的头文档 (.h 文件) 与实现文档 (.c 文件) 都作为程序文档化对象
EXAMPLE_PATTERNS = *.c *.h
# 递归遍历示例程序目录的子目录,寻找被文档化的程序源文件
EXAMPLE_RECURSIVE = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCES_LINK_SOURCE = YES
# 生成 latex 格式的程序文档
GENERATE_LATEX = YES
# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
#让doxygen从配置文件所在的文件夹开始,递归地搜索所有的子目录及源文件
RECURSIVE = YES
#在最后生成的文档中,把所有的源代码包含在其中
SOURCE_BROWSER = YES
$这会在HTML文档中,添加一个侧边栏,并以树状结构显示包、类、接口等的关系
GENERATE_TREEVIEW = ALL
#生成chm格式的压缩html文档
GENERATE_HTMLHELP = YES
# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
# documentation are documented, even if no documentation was available.
# Private class members and static file members will be hidden unless
# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
# will be included in the documentation.
EXTRACT_PRIVATE = NO
# If the EXTRACT_STATIC tag is set to YES all static members of a file
# will be included in the documentation.
EXTRACT_STATIC = NO
5.
1 头文件注释:
/** @brief 这里写你的摘要
* @file 你的文件名
* @author 作者
* @version 版本
* @date 日期
* @note 注解. 例如: 本文件有什么具体功能啊, 使用时要注意什么啊..
* @since 自从...
*/
2 函数的注释:
/** 这里写这个函数的概述
@param[in] 输入参数1
@param[in] 输入参数2
@param[out] 输出参数1
@return 返回值解释一下
@warning 警告: 例如: 参数不能为空之类的
@note 注解
@see 类似于请参考xxoo函数之类的
*/
6. 使用"doxygen cfg-file-name"执行配置,开始生成文档;
7. GENERATE_HTMLHELP设置了这个选项的话,可以使用 EasyCHM转换工具 对html文件夹中的html文档生成chm文件;
8.4. 给source insight添加doxygen注释风格
2. 下载doxygen的二进制文件(下载源码自己编译太麻烦,这里直接下载bin二进制文件);参考http://www.stack.nl/~dimitri/doxygen/manual/install.html。
3. 执行“./configure” 生成makefile文件;执行“make install”安装doxygen;
4. 使用“doxygen -g <cfg-file-name>”生成配置文件,如果不指定名称,默认Doxyfile, 指定"-s"选项的话,可以生成无注释的配置文件;
可以阅读Doxyfile文件中的各个选项设置自己所需配置。这里提供一部分修改配置文件中的选项:一些设置如下:
############配置文件的部分内容#############
# 项目名称,将作为于所生成的程序文档首页标题
PROJECT_NAME = "Test"
# 文档版本号,可对应于项目版本号,譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER = "1.0.0"
# 程序文档输出目录
OUTPUT_DIRECTORY = ./out/
# 程序文档语言环境
OUTPUT_LANGUAGE = Englist
# 如果是制作 C 程序文档,该选项必须设为 YES,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型,只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = YES
# 在 C++ 程序文档中,该值可以设置为 NO,而在 C 程序文档中,由于 C 语言没有所谓的域/名字空间这样的概念,所以此处设置为 YES
HIDE_SCOPE_NAMES = YES
# 让 doxygen 静悄悄地为你生成文档,只有出现警告或错误时,才在终端输出提示信息
QUIET = YES
# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS = *.h
# 递归遍历当前目录的子目录,寻找被文档化的程序源文件
RECURSIVE = YES
# 示例程序目录
EXAMPLE_PATH = example/
# 示例程序的头文档 (.h 文件) 与实现文档 (.c 文件) 都作为程序文档化对象
EXAMPLE_PATTERNS = *.c *.h
# 递归遍历示例程序目录的子目录,寻找被文档化的程序源文件
EXAMPLE_RECURSIVE = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCES_LINK_SOURCE = YES
# 生成 latex 格式的程序文档
GENERATE_LATEX = YES
# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
#让doxygen从配置文件所在的文件夹开始,递归地搜索所有的子目录及源文件
RECURSIVE = YES
#在最后生成的文档中,把所有的源代码包含在其中
SOURCE_BROWSER = YES
$这会在HTML文档中,添加一个侧边栏,并以树状结构显示包、类、接口等的关系
GENERATE_TREEVIEW = ALL
#生成chm格式的压缩html文档
GENERATE_HTMLHELP = YES
# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
# documentation are documented, even if no documentation was available.
# Private class members and static file members will be hidden unless
# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
# will be included in the documentation.
EXTRACT_PRIVATE = NO
# If the EXTRACT_STATIC tag is set to YES all static members of a file
# will be included in the documentation.
EXTRACT_STATIC = NO
5.
1 头文件注释:
/** @brief 这里写你的摘要
* @file 你的文件名
* @author 作者
* @version 版本
* @date 日期
* @note 注解. 例如: 本文件有什么具体功能啊, 使用时要注意什么啊..
* @since 自从...
*/
2 函数的注释:
/** 这里写这个函数的概述
@param[in] 输入参数1
@param[in] 输入参数2
@param[out] 输出参数1
@return 返回值解释一下
@warning 警告: 例如: 参数不能为空之类的
@note 注解
@see 类似于请参考xxoo函数之类的
*/
6. 使用"doxygen cfg-file-name"执行配置,开始生成文档;
7. GENERATE_HTMLHELP设置了这个选项的话,可以使用 EasyCHM转换工具 对html文件夹中的html文档生成chm文件;
8. yum install texlive-latex, 就可以在latex文件夹下运行make生成pdf。
========================================================================
更详细的一个注释说明如下:
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
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注释风格