Doxygen配置（翻译）

使用Doxygen文档开发工具时需要进行的配置：



可执行文件 doxygen 是原代码分析和生成文档的主要工具. 请看 Doxygen usage 章节来获取更详细的使用帮助.

Doxytag可执行文件---仅仅是用来实现帮助程序员生成不需要看原代码就能了解工程部署信息的doxygen文档的参考文档( 例如：那些使用doxygen生成的文档).请看Doxytag usage 章节来获得更多的使用帮助.

doxywizard 可执行文件很容易就能使用,它是用来为doxygen工具提供配置信息的一个图形化工具.

下面的图显示了开发工具之间的相互关系信息:




~dimitri/doxygen/infoflow.gif

图：Doxygen information flow




Step 1: 创建一个配置文件
Doxygen使用一个配置文件来确定它所有的设置. 每个工程都应该有它自己的配置文件.

一个工程可以只有一个原文件, 也可以是工程中所有原文件的递归扫描得到的原文件的树状视图。

为了简化doxygen生成配置文件的工作, doxygen 可以为你提供一个模板化的配置文件.

1. 为了创建一个模板化的配置文件，只需要调用doxygen并从命令行中敲入-g:

doxygen -g <config-file>
其中 <config-file>是某个模板化的配置文件的文件名. 如果你省略了文件名, doxygen会为你生成一个默认的Doxyfile的配置文件. 如果<config-file>是一个已经存在的文件名, doxygen 在生成配置模板之前，将会生成一个 <config-file>. Bak备份文件。

2. 如果你使用 - (例如：减号) 作为文件名doxygen将会把你从键盘输入的文字当作配置文件名。

配置文件有着和Makefile相似的格式.主要是：包含了很多的“标志”分配符格式 (tags):

例如：

TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 ...

在生成文档模板时，你可以使用默认（即：保留大多数的TAGS）详细信息请看 Configuration 这一章节来获取更多的信息.

如果你不想使用文本编辑工具来编写配置文件,你应该看看 doxywizard 章节的描述, 它是一个可以用来创建/读/写doxygen 配置文档的图形化工具，同时它也可以在路径中进行全路径配置来使doxygen正常工作。

3. 对于一个有很少的原文件和头文件组成的C/C++工程来说, 你可以保留 INPUT 标志为“空” ，那么 doxygen 将会在当前路径下搜索原文件.

4. 如果你的工程很大，你应该把你的工程文件的“根目录”放在INPUT标志后面,需要添加到工程中的文件应该放到FILE_PATTERNS 标志之后(例如： *.cpp *.h). 至少是匹配了1项的文件才能被doxygen程序读入并分析(如果省略了这项设置，则会使用doxygen配置列表中的格式).

5. 如果想要递归对原文件树进行分析必须设置RECURSIVE标志为 YES.

6. 想在doxygen中使用更多的自定义规则进行分析，必须使用EXCLUDE标志和 EXCLUDE_PATTERNS标志。

7. 想忽略所有的 test路径下的文件，使用下面的形式:

EXCLUDE_PATTERNS = */test/*
8. 对于C/C++文件Doxygen通常直接进行分析。 如果文件有 .idl或 .odl 扩展名，则doxygen会把它视为 IDL文件。

8. 有.java 扩展名的将被视为Java文件.

9. 使用 .cs作为扩展名的文件将会视为C# 文件.

10. 使用.php, .php4扩展名的文件和用.inc 或 .phtml 扩展名的文件将被视为PHP 原文件.

11. 如果你想用doxygen为已经存在的工程生成文档。你首先要想象一下你的工程文档最终使用什么样的格式排版，为了实现这样的目标，你必须要设置EXTRACT_ALL 标志为YES. 然后，doxygen表现出来的是它知道了所有你的工程文件的配置目标。

注意：如果设置EXTRACT_ALL 标志为YES 。则：undocumented members 之类的警告将不会再产生。

12. 使用doxygen来分析一个现存的源代码的某个部分或全部文件可以更清晰的明白源代码各个功能模块的定义和要实现的功能以及它们之间的交叉参考。

13. 使用Doxygen 生成交叉参考必须设置SOURCE_BROWSER 标志为 YES。也可以直接通过设置INLINE_SOURCES 标志为 YES 来实现把工程的所有源代码包含进文档中。(这样方便了代码的通览).

Step 2: Running doxygen
To generate the documentation you can now enter:

doxygen <config-file>
Doxygen 将会在输出路径中创建html, rtf, latex和/或man 路径。 路径和路径中的文件格式是对应的HTML, RTF, 和Unix-Man格式.

默认的路径是doxygen的安装路径。可以使用 OUTPUT_DIRECTORY, HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, 和MAN_OUTPUT标志来自定义配置文档的输出路径。如果输出路径不存在doxygen将会为你创建一个输出路径。

生成的 HTML 可以通过使用浏览器浏览位于html路径下的 index.html 文件. 如果浏览器支持层叠样式表 (CSS) 那就更棒了。

生成的 必须要先用 编译器进行编译(我使用 teTeX 0.9版本，其中包含了 3.14159). 为了简化编译文档的生成过程，doxygen在latex 路径下提供了一个Makefile 。在命令行latex路径下敲入 make将会生成一个refman.dvi文件。 (假设你有一个文件叫做make of course). 你可以通过使用xdvi命令来查看这个文件或者使用dvips把它转换成一个后缀是.ps的文件 refman.ps。

想实现分成2页的效果可以使用make ps_2on1命令。Postscript文件最终会被发送到Postscript打印机输出。如果你没有Postscript打印机，你可以使用ghostscript 命令把Postscript文件格式转换成你的打印机能够识别的文件格式。如果你已经安装了ghostscript 解释程序，那么可以把文件转换成 PDF格式，这只需要敲入make pdf (或make pdf_2on1)。

想生成PDF文件，你要把 PDF_HYPERLINKS 标志设置成YES。

产生的man页面文件可以通过man程序来进行查看。但是，你必须确定man路径有相应的环境变量设置 (一般在 MANPATH环境变量中)。注意：man页面文件的格式有一些限制 ，所以有些信息(像：class图，交叉参考，公式等)将会丢失掉。

Step 3: Documenting the sources
尽管源代码编制文档的被作为第3步，但是，在某些新的工程中，这个是作为第1步来做的。 这里，我假设你已经有了一些想用doxygen来对其进行文档化（描述API接口和作用）的源代码。

如EXTRACT_ALL 选项被设置成NO（默认情况下是NO ）那么doxygen只会为已经文档化的成员，文件，类和命名空间生成文档。如果你的文档属于这种情况，该怎么办呢？对于成员，类和命名空间有2种基本的设置：

1.成员，类或命名空间的前面安排一个描述或定义的块儿。对于文件，类和命名空间成员来说，doxygen 允许直接在成员后面安排文档。你可以参考：

Special documentation blocks 了解更多特殊块儿的设置。

2. 想在任何地方部署特殊的文档块儿（任何的文件或任何的路径）和在文档块中添加一个“结构化”的命令。“结构化”的命令用来设置一个可被编制成文档的链接。 (e.g. a member, class, namespace or file)。请看：Documentation at other places 了解更多的结构化命令的使用方法。

文件只能使用上面2中的方法进行设置，因为没有办法把一个文档块儿放到一个文件的前面。

当然，文件成员（函数，变量，类型定义，define）不需要显示的使用“结构化”命令，只需要把特殊的文档块儿放到文件中的最前面或最后面就可以了。

文档内部的文档块儿在输出为HTML格式或其他格式输出文件之前进行doxygen的语法分析：

它其实是在进行下面的步骤前进行分析：

文档内部的特殊“结构化”命令被执行的时候。请看： Special Commands 章节获取所有的命令参考信息。
如果某行中使用“空格+后面使用1个或多个*号”，或者是很多的“空格”符，则所有的空格和“*”号都会被删除。
所有的“空行”都会被视为“图形分隔符”。这项安排可以使你有“部署自定义图形分隔符”的能力，以产生更具可读性的文档。
Doxygen将会为所有已经归档的classes生成链接。
如果在文档中找到符合doxygen文档格式的成员，那么也会为members创建链接。请参考：Automatic link generation获取更多的如何自动化文档链接。
文档中的HTML标志被解释和转换成相应的输出。请看：HTML Commands章节获取更多的关于HTML标志的使用信息。


作者Blog：