Doxygen代码文档生成工具简单介绍与使用

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. 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

8.4.  给source insight添加doxygen注释风格

请参考：http://blog.csdn.net/dayong419/article/details/7932467  

 

[参考]http://blog.csdn.net/joyjj0218/article/details/48084551