使用Doxygen生成代码文档

Doxygen 是一种用于 C/C++、Java™、Python 和其他编程语言的文档系统, 其功能类似于 java.

1. 安装doxygen

安装doxygen前最好先安装graphviz软件包, 不然可能会安装不成功:

sudo apt-get graphviz

参考官方的安装教程. 这一步还是非常容易的, 如果没有root权限, 可以使用 --prfix 参数指定安装目录:

./configure --prefix=/home/user1/bin

2. 使用doxygen生成文档

用doxygen命令来生成文档需要指定一个配置文件, 初次使用时可以执行 doxygen -g 命令, 执行完成后会在当前目录下生成一个默认的配置文件模板 Doxyfile , 该文件中包含了丰富的有关配置参数的注释, 高级用户可以好好研究下. 也可用doxygen -g filename 指定配置文件名. 然后执行 doxygen Doxyfile 命令开始就可以开始生成代码文档了, 文档保存在当前目录的html/目录中, 非常简单吧.
doxygen不仅可以生成html文件, 也可以生成pdf, man pages, rtf, latex, xml, chm等多种格式的文档, 默认生成html和latex, 只需要在配置文件中设置相应的 <GENERATE_MAN>, <GENERATE_RTF>,<GENERATE_HTMLHELP>, <GENERATE_XML>  等相应的标签为
YES 即可.

3. 编辑配置文件 Doxyfile

配置文件采用 TAG = value [value, ...] 这样的结构，与 Make 文件格式相似。可以仔细看看默认生成的Doxyfile文件, 里面每个标记都有注释, 下面是最重要的标记：

<OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。
<INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。例如，请考虑以下代码片段：

INPUT = /home/user1/project/kernel /home/user1/project/memory

             在这里，doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把<RECURSIVE> 标记设置为
Yes。
<EXCLUDE>:
从文档目录排除相应的目录

<FILE_PATTERNS>：在默认情况下，doxygen 会搜索具有典型 C/C++ 扩展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果 <FILE_PATTERNS> 标记没有相关联的值，doxygen 就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用 .c86 作为 C 文件扩展名，就应该在
<FILE_PATTERNS> 标记中添加这个扩展名。

<RECURSIVE>：如果源代码层次结构是嵌套的，而且需要为所有层次上的 C/C++ 文件生成文档，就把这个标记设置为 Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如果这个标记设置为
Yes，doxygen 就会递归地搜索整个层次结构并提取信息。

<EXTRACT_ALL>：这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为Yes。

<EXTRACT_PRIVATE>：把这个标记设置为Yes。否则，文档不包含类的私有数据成员。

<EXTRACT_STATIC>：把这个标记设置为Yes。否则，文档不包含文件的静态成员（函数和变量）。

4. doxygen 中的特殊标记

Doxyfile 中的 <ENABLE_PREPROCESSING> 标记在默认情况下设置为 Yes。为了执行宏展开，还应该把 <MACRO_EXPANSION> 标记设置为 Yes。

在文档中，可能希望只展开特定的宏。为此，除了把 <ENABLE_PREPROCESSING> 和 <MACRO_EXPANSION> 标记设置为 Yes之外，还必须把
<EXPAND_ONLY_PREDEF> 标记设置为 Yes（这个标记在默认情况下设置为 No），并在<PREDEFINED> 或 <EXPAND_AS_DEFINED>
标记中提供宏的细节。如:

ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED = CONTAINER

只展开宏 CONTAINER .

5. 生成图形和图表

在默认情况下，Doxyfile 把 <CLASS_DIAGRAMS> 标记设置为 Yes。这个标记用来生成类层次结构图。要想生成更好的视图，可以从Graphviz 下载站点 下载 dot 工具。Doxyfile 中的以下标记用来生成图表：
<CLASS_DIAGRAMS>：在 Doxyfile 中这个标记默认设置为 Yes。如果这个标记设置为 No，就不生成继承层次结构图。
<HAVE_DOT>：如果这个标记设置为 Yes，doxygen 就使用 dot 工具生成更强大的图形，比如帮助理解类成员及其数据结构的协作图。注意，如果这个标记设置为 Yes，<CLASS_DIAGRAMS> 标记就无效了。
<CLASS_GRAPH>：如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes，就使用 dot 生成继承层次结构图，而且其外观比只使用 <CLASS_DIAGRAMS> 时更丰富。
<COLLABORATION_GRAPH>：如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes，doxygen 会生成协作图（还有继承图），显示各个类成员（即包含）及其继承层次结构。

6. 代码文档样式

如果使用C/C++, 最简单的注释风格就是

/**
* text...
*
*/

也可以加一些标记, '@' 和 '/' 等价:

/**
* @brief bababa
*
* detailed info....
*
*/

Doxygen 允许一条简短注释,加上一条详细注释.其格式也是多样的. 一般,在 JAVADOC_AUTOBRIEF = NO时,简短注释(///@brief )后空一行,然后再是详细注释. 当 JAVADOC_AUTOBRIEF = YES时,并且简短注释以第一个句号结束,句号后跟一空格(即'. ');或者是新起一行,就可以写详细注释了.

如果同一代码条目在声明和定义处都有简短注释和详细注释, 则文档只采用声明前的简短注释和定义前的详细注释.

如果是在行尾注释变量,参数等,在你选用的注释格式后面加上'<', 如: ///<行尾的注释.

下面有一个注释的例子:

----------------------------- Example Begin ---------------------------------
///@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 class of server socket.
class socket_c
{
private:

public:
///@brief handle the connections of clients.
///@param server the server ip address.
///@param serv_port the server #port.
///@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 ---------------------------------

7. 在vim中使用Doxygen插件:
DoxygenToolkit

该插件可以自动生成Doxygen注释, 非常方便. 安装好之后, 需要在VIM的配置文件中(/etc/vimrc)为doxygentoolkit这个插件配置一些全局变量：

let g:doxygenToolkit_authorName="your name"

let g:doxygenToolkit_briefTag_funcName="yes"

参考:
http://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/#resources

http://www.cnblogs.com/etangyushan/p/3753879.html

http://blog.csdn.net/Augusdi/article/details/6233164