• 编程技能：编写可读可维护的代码
• 编程技巧：编写优化高效的代码

简介

开源跨平台的注释文档生成工具。

安装

1. 下载
2. 解压tar zxvf doxygen压缩包
3. 切换到解压后的doxygen主目录cd doxygen解压目录
4. 创建build目录mkdir build
5. 切换到build目录cd build
6. 生成Linux Makefilecmake -G "Unix Makefiles" ../
7. 编译make
8. 安装make install

使用

1. 进入项目目录cd 项目目录
2. 生成配置文件doxygen –g (默认配置文件名为Doxyfile)
3. 生成文档文件doxygen

配置文件

# 项目名称，将作为于所生成的程序文档首页标题
PROJECT_NAME        = “Test”
# 文档版本号，可对应于项目版本号，譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER      = "1.0.0
# 程序文档输出目录
OUTPUT_DIRECTORY    =  /home/user1/docs
 
# 程序文档输入目录 
INPUT                = /home/user1/project/kernel
 
# 程序文档语言环境
OUTPUT_LANGUAGE      = Chinese
DOXYFILE_ENCODING  = UTF-8
# 只对头文件中的文档化信息生成程序文档 
FILE_PATTERNS        = 
 
# 递归遍历当前目录的子目录，寻找被文档化的程序源文件 
RECURSIVE            = YES 
# 如果是制作 C 程序文档，该选项必须设为 YES，否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C  = YES
 
#提取信息，包含类的私有数据成员和静态成员
EXTRACT_ALL            = yes
EXTRACT_PRIVATE        = yes
EXTRACT_STATIC        = yes
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT  = YES
# 在 C++ 程序文档中，该值可以设置为 NO，而在 C 程序文档中，由于 C 语言没有所谓的域/名字空间这样的概念，所以此处设置为 YES
HIDE_SCOPE_NAMES      = YES
# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息
QUIET  = YES
# 递归遍历示例程序目录的子目录，寻找被文档化的程序源文件
EXAMPLE_RECURSIVE      = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
REFERENCES_LINK_SOURCE = YES
# 不生成 latex 格式的程序文档
GENERATE_LATEX        = NO
# 在程序文档中允许以图例形式显示函数调用关系，前提是你已经安装了 graphviz 软件包
HAVE_DOT              = YES
CALL_GRAPH            = YES
CALLER_GRAPH          = YES
#在最后生成的文档中，把所有的源代码包含在其中
SOURCE BROWSER        = YES
$这会在HTML文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系
GENERATE TREEVIEW      ＝ ALL

语法简介

• 简单注释
• 单行注释：///或者//!
• 多行注释：/**或者/*!
• 文件注释

/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @mainpage 工程概览
 * @author 作者
 * @version 版本号
 * @date 年-月-日
 */

• 全局常量/变量/宏定义/结构体定义/类定义的注释
• 代码前注释

/// 注释
全局常量/变量/宏定义/结构体定义/类定义

例如：

/// 缓存大小
#define BUFSIZ 1024*4

• 代码后注释

全局常量/变量/宏定义/结构体定义/类定义 ///< 注释

例如：

#define BUFSIZ 1024*4 ///< 缓存大小

• 函数注释

/**
 * @brief 函数简介
 *
 * @param 形参 参数说明
 * @param 形参 参数说明
 * @return 返回值说明
*/

例如：

/**
 * @brief 主函数
 * @details 程序唯一入口
 *
 * @param argc 命令参数个数
 * @param argv 命令参数指针数组
 * @return @c 0 程序执行成功
 *               @c 1 程序执行失败
*/
int main(int argc, char* argv[]){
}

• 其它常用命令

其他

• 使用Visual Assist X进行快捷doxygen模板注释