doxygen

Doxygen把自己定义为“Source code documentation generator tool”（源代码文档生成工具）。Doxygen提供一种维护文档的机制。Doxygen可以做下面的事情：

1、从已经文档化的代码中抽取并生成文档。生成的文档格式有html、xml、Tex、rtf、PostScript、带链接的PDF、chm、Unix man pages等等多种格式，由于是xml是高度结构化的，所以你可以通过第三方工具做得更好。

2、从没有文档化的代码中生成代码结构的文档。此时可以让读者快速对代码树的结构产生的整体概念，为进一步阅读打好基础。

Doxygen有3个工具的集合，其中doxygen是工具集的核心，此外还存在一个名为doxytag的工具，用于合并已有的文档，剩下的一个就是前面的两个工具的GUI前端doxywizard。

Doxygen安装方法

1、ubuntu下我使用的是sudo apt-get install doxygen

2、源代码编译方式安装，我没有试过。网上搜集的命令如下

bash-2.05$ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn

bash-2.05$ cd doxygen-svn

bash-2.05$ ./configure –prefix=/home/user1/bin

bash-2.05$ make

bash-2.05$ make install

Doxygen的使用方法：

1、在项目所以在目录运行：doxygen -g [config-file]，其中config-file是一个文件名，可以省略，默认值为当前目录的Doxyfile，里面是UNIX风格的设置──一个变量对应一个值，用等号相连。运行这个命令将会生成一个相应的设置文件，它是默认的。

2、根据需要修改上面的config-file，这是一个普通的文本文件，里面存在大量注释，以帮助我们理解一个设置的含意。作为简单的尝试，你可以省去这步。这里可能有一个设置比较重要，就是生成的文档放在哪里，默认会生成在当前目录里。

3、在项目目录里运行命令：doxygen，没有任何参数，此时会根据上面的设置文件生成满足要求的文档，如果设置文件里指定了生成HTML的文档，那么生成相应的HTML文档。当然其它格式也可以。

编辑配置文件

配置文件采用 <TAGNAME> = <VALUE> 这样的结构，与 Make 文件格式相似。下面是最重要的标记：

<OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。

<INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。例如，请考虑以下代码片段：

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

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

<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。否则，文档不包含文件的静态成员（函数和变量）。

生成多种格式的文档的 Doxyfile 

#for HTML 

GENERATE_HTML = YES

HTML_FILE_EXTENSION = .htm

#for CHM files

GENERATE_HTMLHELP = YES

#for Latex output

GENERATE_LATEX = YES

LATEX_OUTPUT = latex

#for RTF

GENERATE_RTF = YES

RTF_OUTPUT = rtf 

RTF_HYPERLINKS = YES

#for MAN pages

GENERATE_MAN = YES

MAN_OUTPUT = man

#for XML

GENERATE_XML = YES

注释源代码

Doxygen支持多种风格的源代码注释，也支持自定义风格的注释

一个例子：

/**

 * @file doxygen.cpp

 * @author abc

 *

 * @brief 这是一个使用Doxygen工具的示例

 * 

 * @details 大家注意到没有，如上面的\@file等等实际上是Doxygen支持的命令 \n

 * 命令是用来帮助Doxygen对相应的信息定位的工具， \n

 * 上面3个命令意义大家一看就明白了。\n

 * Doxygen存在大量命令，官方手册有命令

 */

/**

 * @brief 一个示例类

 */

class Example

{

public:

        /**

         * @brief 打印内部保存的值

         * @return 自身的引用

         */

        Example& print()

        {

                std::cout << _num << std::endl;

                return *this;

        }

        /**

         * @brief 设置内部的值

         * @param num 需要设置的值

         * @return 自身的引用

         */

        Example& set(int num)

        {

                _num=num;

                return *this;

        }

private:

        int _num;

}

Doxygen命令官方手册:http://www.stack.nl/~dimitri/doxygen/commands.html