使用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 = YESMACRO_EXPANSION = YESEXPAND_ONLY_PREDEF = YESEXPAND_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.cppint 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