doxygen学习笔记 2012-02-28

Doxygen把本身定义为“Source code documentation generator tool”（源代码文档生成工具）。Doxygen提供一种维护文档的机制。Doxygen能够作下面的事情：

一、从已经文档化的代码中抽取并生成文档。生成的文档格式有html、xml、Tex、rtf、PostScript、带连接的PDF、chm、Unix man pages等等多种格式，因为是xml是高度结构化的，因此你能够经过第三方工具作得更好。

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

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

Doxygen安装方法

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

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

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的使用方法：

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

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

三、在项目目录里运行命令：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