Doxygen 文档注释详解

转自：http://hi.baidu.com/seest/blog/item/efb5264cd21a4dfad72afc02.html

用 Doxygen 自动生成文档

大家在平时的编程过程中,都会在代码中插入一些注释,对文件,类,函数,全局变量等进行简单说明.项目完成后,一般也要编写项目的文档,如何利用源代码及其中的注释,自动生成图文并茂的文档,就是下面要介绍的.

1 工具

文档自动生成的工具软件,除了商业化的如Rational SoDA等,更有开源的Doc++和Doxygen等. 本文主要介绍功能全面的Doxygen.
Doxygen可以对C++, C, Java, Python等语言进行解析并生成HTML,LaTeX,RTF,man page,XML等格式的文档.

除了必备的Doxygen (http://www.stack.nl/~dimitri/doxygen/), 如果你还想生成漂亮的类图等,还需要下载graphviz (Doxygen 采用的绘图工具,http://www.graphviz.org/Download..php).


2 Doxygen 的注释格式

Doxygen 的注释格式十分灵活.可以是JavaDoc, Qt和仿c++风格, 并且可以混合使用. 如果你熟悉Doc++,就按照你以前的风格写好了:). 下面对每种风格简单举例:

-- JavaDoc风格:
/**
* your comment text.
*/
-- Qt风格:
/*!
* your comment text.
*/
-- 仿c++风格:
/// //!
/// your comment text. 或者: //! your comment text.
/// //!

因为我一直喜欢用c++的单行注释风格(即'//'),所以下面举例就以仿c++风格为例. 下面注释中的'@'和'/'等价,可以根据爱好选用.
因为是在头文件中定义接口,所以注释也就主要集中于头文件中. 如果你想在实现文件中注释,其效果和在头文件中是一样的.下面就举一个实例.

备注:a) '#' 后面的注释是我加的简单解释.不属于文档注释内容.
b) Doxygen 允许一条简短注释,加上一条详细注释.其格式也是多样的. 一般,在 JAVADOC_AUTOBRIEF = NO时,简短注释(///@brief )后空一行,然后再是详细注释. 当 JAVADOC_AUTOBRIEF = YES时,并且简短注释以第一个句号结束,句号后跟一空格(即'. ');或者是新起一行,就可以写详细注释了.示例如下:

# 简短注释. 详细注释.
/// Brief description which ends at this dot. Details follow
/// here.

c) 如果同一代码条目在声明和定义处都有简短注释和详细注释, 则文档只采用声明前的简短注释和定义前的详细注释.
d) 如果是在行尾注释变量,参数等,在你选用的注释格式后面加上'<', 如: ///<行尾的注释.


----------------------------- Example Begin ---------------------------------
# 文件的注释格式
# 注释文件,格式: ///@file 文件名 文件的简短注释.
///@file socket_c.h head file of class socket_c.
# 文件的详细注释.
///Define the interface of class socket_c.
# 普通注释,不会生成在文档中.
//$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $

# 类的注释,格式: ///@brief 简短注释内容.
///@brief class of server socket.
class socket_c
{
private:

public:
# 函数的注释格式
# 函数的注释,格式: ///@brief 函数的简短注释.
///@brief handle the connections of clients.
# 参数注释,格式: ///@param 参数的简短注释.
///@param server the server ip address.
///@param serv_port the server #port.
# 返回值注释,格式: ///@return 返回值的简短注释.
///@return connected socketfd.
# 具体返回值的注释,格式: ///@retval 返回值 该返回值的注释.
///@retval connfd on success.
///@retval 0 on EINTR - system call.
///@retval -1 on error.
# 参见...,格式: ///@see 参见的类/文件等.
///@see main_ppc.cpp
int accept_client(const int listenfd);
};

# 自定义类型的注释
///@brief structure of child process.
struct child_proc_s
{
# 行尾的注释,格式: ///< 注释内容.
pid_t child_pid; ///<child process id.
int child_pipefd; ///<parent's stream pipe to/from child.
};

# 全局变量的注释,也可以采用上面的行尾格式进行注释.
///gloable variable for signal.
pid_t g_pid = 0;
----------------------------- Example End ---------------------------------


3 配置文件的生成与修改

Doxygen的功能强大,配置选项也十分多. 如果是命令行模式, 有些不便. 因此建议使用GUI的Doxywizard(可以从<开始>菜单中运行). 下面就对我个人认为比较重要的选项,并结合实例 (生成html文档) 进行简单说明.
下面列出的一般是需要修改的,未列出的我采用缺省值.

# Project选项
#---------------------------------------------------------------------------
# Staff_TPC是生成文档的项目名,会显示在文档中.
PROJECT_NAME = Staff_TPC
PROJECT_NUMBER = 1.0 # 项目版本号
# 生成文档的输出路径
OUTPUT_DIRECTORY = "f:/My Documents/cpp/horin/staff/"
# 生成文档的语言,缺省是English,也可以是简体中文等.
OUTPUT_LANGUAGE = English
JAVADOC_AUTOBRIEF = YES # 打开此选项.

# Build 选项
#---------------------------------------------------------------------------
SHOW_INCLUDE_FILES = NO # 不显示所有包括的文件.

# input 选项
#---------------------------------------------------------------------------
# 要生成文档的源文件的路径. 如果是一个目录,则是该目录下的所有文件; 当然,也可以
# 是具体的某个文件.
INPUT = "f:/My Documents/cpp/horin/staff/tpc/"
# 输入文件的匹配模式,下面是c / c++语言的设置.
FILE_PATTERNS = *.c /
*.cpp /
*.h /
*.hpp
RECURSIVE = YES # 需要递归处理子目录.

# source browser选项
#---------------------------------------------------------------------------
# 如为SOURCE_BROWSER和INLINE_SOURCES都设置为YES, 则生成的文档中会包括源代码
# (即.cpp文件),这可以方便阅读时查看源代码.
SOURCE_BROWSER = NO
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES # 忽略普通的文档注释.
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
VERBATIM_HEADERS = YES

# HTML 选项
#---------------------------------------------------------------------------
GENERATE_HTML = YES # 需要生成html格式的文档.
GENERATE_HTMLHELP = YES # 需要生成windows HTMLHELP格式的目录,以方便阅读.
GENERATE_TREEVIEW = YES # 需要生成树视图,以方便阅读.

# LaTeX 选项
#---------------------------------------------------------------------------
GENERATE_LATEX = NO # 不需要生成LaTeX输出.

# dot 选项 # 此选项是生成图形,建议(需要)安装graphviz.
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = YES
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = YES # 已经安装graphviz.打开此选项.
CLASS_GRAPH = YES # 生成类图
COLLABORATION_GRAPH = YES # 生成协作图
UML_LOOK = NO

在上面根据自己的需要对各个选项进行了配置,下面很重要的一步,就是把配置保存下来. 呵呵,这是大家最擅长的了. 可以命名配置文件为Doxygen-YourName.txt, 今后只需修改project和input选项,即可重用.


4 文档的生成

在Doxywizard中打开上面的配置文件Doxygen-YourName.txt, 根据需要修改project和input选项(也可以在文本编辑器中直接修改Doxygen-YourName.txt), 点击菜单Doxygen->Run(ctrl+r),稍微休息一会,你就可以看到在OUTPUT_DIRECTORY路径下生成了一个html的子目录.该子目录下就是你需要的文档. 运行index.html文件, 是否见到了你想要的.很有可能,还见到了你意想不到的.


5 Doxygen的其他用途

Doxygen配合graphviz, 可以生成UML设计图形,如类图,协作图. 如你拿到一份源代码,因为类的关系复杂,或者没有文档, 此时你就可以利用Doxygen来进行简单的反向工程了.