doxygen 中文 （Getting started （入门指南））

doxygen的HP：~dimitri/doxygen/index.html
doxygen的手册：~dimitri/doxygen/manual.html


Doxygen 介绍(中文):
http://ticktick.blog.51cto.com/823160/188671
由于主题的关键词设置的不是特别好，所以搜索好几次后，才找到，学习。


该手册的 目录 和 第一部分的Section ，网上有中文译版。



本文是第一部分Section 的中文译文。

目录 例：
This manual is divided into three parts, each of which is divided into several sections.

The first part forms a user manual:

• Section discusses how to , compile and install doxygen for your platform.
• Section tells you how to generate your first piece of documentation quickly.
• Section Documenting the code demonstrates the various ways that code can be documented.
• Section show various ways to create lists.
• Section shows how to group things together.
• Section shows how to insert formulas in the documentation.

.........................

Getting started （入门指南）

可执行的doxygen是主程序，解析soources和生成文档。

看章节，了解更详细的用法信息。

可执行的doxytag仅当如果你想为没有sources的内容产生外部文档(也就是由doxygen产生的文档)时才必要。

看章节，了解更详细的用法信息。

可选用，可执行的doxywizard能使用，由（图形前台）来编辑doxygen 使用的configuration文件，以图形环境下运行。

Mac OS X的doxywizard将被启动，当点击Doxygen应用图标时。

下图显示显示这个工具的信息流程图（看起来复杂，仅是为了使其完整）：

Doxygen信息流程图

Step 1: Creating a configuration file（创建一个configuration文件）

Doxygen用一个configuration文件决定所有的设置选项。每一个project都将得到他自己的configuration文件。一个project能由一个单独的source文件构成，但也能由一个全部的向下递归的source tree组成。

简单的创建configuration文件，doxygen能为你创建一个模板configuration文件。
在命令行中，调用下面的命令（含-g选项）：

doxygen -g 

是这个configuration文件的名字。
如果你忽略这个文件名的话，一个名为Doxyfile的文件将被创建。
如果一个名为的文件已经存在，doxygen将在生成configuration模板文件之前，重命名该文件为.bak。
如果你用 - (也就是减号)作为文件名，doxygen将尝试从能被脚本处理使用的用的标准的输入(stdin) 读取这个configuration文件。
这个configuration文件具有固定格式，与Makefile较为相似。
其包含分配(tags)数字，如下：

TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 ...

你或许能把大部分的tags的值设定在生成的模板configuration文件中，作为默认值。
看章节，了解关于configuration文件的更详细的信息。

如果你不希望用文本编辑器编辑这个配置文件，你可以看看，能通过GUI界面（GUI前台）创建、读取、写入doxygen configuration文件，也允许通过对话框键入，设定configuration选项

对于一个小的包含C、C++源文件和头文件的工程文件，你能保留tag为空，doxygen将在当前目录下搜索源文件。

如果你有一个较大的包含源程序目录或树，你将指定 tag为这个root目录或多个目录，并且在 tag添加一个或多个文件模型（例如：*.cpp *.h）。
仅有在模型中匹配的文件被解析（如果模型被忽略，很多源文件扩展会被使用）。
为了递归解析源文件树，你必须设置RECURSIVE tag为YES。
为了进一步微调这个被解析的文件列表，和 tags可被使用。
从这个源文件树中忽略所有的测试目录，如下例：

EXCLUDE_PATTERNS = */test/* 

Doxygen考虑文件的扩展名来决定如何解析文件。
如果一个文件是.idl or .odl的扩展名，他将被当做IDL文件来处理。
如果有一个.java的扩展名，他将被当做Java文件。
文件以.cs结尾被视作C#文件，.py为扩展名，会选择Python解析器。
最终，文件的扩展名为.php, .php4, .inc or .phtml将被视作PHP的源文件。
一些其他扩展的文件被解析，如果是C/C++文件的话。.m文件被视为Objective-C的源文件。

如果你正在对一个已经存在的工程使用doxygen(还未有任何文档被doxygen知道)，你可以用自己的想法来结构化文档。
这样做，你必须设定configuration文件中的 tag为YES。
然后doxygen将假装文档化在你的源文件中的所有的东西。
请注意，所有作为未文档化的内容的警告信息将不被生成，只要被设定为YES

分析一个定义在源程序文件中的交叉引用的存在的软件片段。
如果你设置了 tag为YES，Doxygen将生成同样的交叉引用。
设置了为YES的话，其也能直接的在文档中包含源文件。（他能方便的评审代码）

Step 2: Running doxygen（运行doxygen）

现在即可键入下记命令生成文档：

doxygen 

依赖你的设定，doxygen将创建html, rtf, latex, xml and/or man目录在Output目录内。
建议这些名字的目录中包含生成的文档包含HTML, RTF, LATEX, XML and Unix-Man page格式。

这个默认的输出目录是doxygen支持的目录。
这个root目录可以被改变。
在输出目录中的格式的特殊目录能被选择，通过configuration 文件中的, , , , and tags。
如果输出目录不存在，doxygen将尝试创建（但是其不会试图创建完整的递归路径，像mkdir –p所作的那样）。

HTML output

这个生成的HTML文档能被HTML浏览器所查看。
在HTML章节中的特点（比如或其他的搜索引擎）需要浏览器支持DHTML和Javascript。

LaTeX output

The generated LATEXdocumentation must first be compiled by a LATEXcompiler (I use a recent teTeX distribution). To simplify the process of compiling the generated documentation, doxygen writes a Makefile into the latex directory.

The contents and targets in the Makefile depend on the setting of . If it is disabled (set to NO), then typing make in the latex directory a dvi file called refman.dvi will be generated. This file can then be viewed using xdvi or converted into a PostScript file refman.ps by typing make ps (this requires dvips).

To put 2 pages on one physical page use make ps_2on1 instead. The resulting PostScript file can be send to a PostScript printer. If you do not have a PostScript printer, you can try to use ghostscript to convert PostScript into something your printer understands.

Conversion to PDF is also possible if you have installed the ghostscript interpreter; just type make pdf (or make pdf_2on1).

To get the best results for PDF output you should set the and tags to YES. In this case the Makefile will only contain a target to build refman.pdf directly.

RTF output

Doxygen结合RTF输出一个名为refman.rtf的单独的文件。
这个文件被最佳化的导入到了Microsoft Word中。
某些信息的编码使用领域。按实际值,你必须选择所有(Edit - select all),然后切换字段(右点击及从下拉菜单中选择)。

XML output

The XML output consists of a structured "dump" of the information gathered by doxygen. Each compound (class/namespace/file/...) has its own XML file and there is also an index file called index.xml.

A file called combine.xslt XSLT script is also generated and can be used to combine all XML files into a single file.

Doxygen also generates two XML schema files index.xsd (for the index file) and compound.xsd (for the compound files). This schema file describes the possible elements, their attributes and how they are structured, i.e. it the describes the grammar of the XML files and can be used for validation or to steer XSLT scripts.

In the addon/doxmlparser directory you can find a parser library for reading the XML output produced by doxygen in an incremental way (see addon/doxmlparser/include/doxmlintf.h for the interface of the library)

Man page output

The generated man pages can be viewed using the man program. You do need to make sure the man directory is in the man path (see the MANPATH environment variable). Note that there are some limitations to the capabilities of the man page format, so some information (like class diagrams, cross references and formulas) will be lost.

Step 3: Documenting the sources（文档化源文件）

尽管文档化源文件出现在step 3，但是在一个新的工程中，必须参照step 1。

如果在配置文件中的为NO（默认值），doxygen将仅生成元素，文件，类和命名的文档。所以你如何文档化他们，主要依据2个选项：

1. 放置一个特殊的文档块在声明和定义元素、类和命名的前面。对于文件，类和命名允许直接放置在元素在成员之后。
   看Special documentation blocks章节，学习更多的关于特殊文档块。
2. 把一个特殊的文本块放置到某处（另一个文件或者另一个位置），并将一个结构指令放入此文本块中。一个结构指令将一个文本块连接到某一个可以被文本化的实体中（比如，一个成员，类，命名或者文件）。查看章节Documentation at other places以学习更多关于结构指令的内容。

文件仅可以被文本化使用第二个选项，因为没有方法将文本块置于文件的前面。当然，文件成员（功能，变量，类型定义，定义）不需要一个明确的结构指令；仅将一个特殊的文本块放置于他们的前面或者后面就可以做到。

被写入至HTML以前并且/或者LATEX输出文件之前，一个特殊的文本块中间的文档被解析。

解析时发生下列步骤：

• 在文本中的特殊的指令被执行，参考章节中所有指令的概要。
• 如果一行以一些空白开头，紧接着一个或者更多的星号(*)，然后是任意更多的空白，那么所有的空白和星号被移除。
• 这样可以节省你把new-paragraph命令你为了使生成的文档的可读性。
  所有的空白行被作为一段分隔。这样可以节省将空间重新分段的指令，使生成的文本具有可读性。
• 为了使文档和文本等级具有一致性，创建链接（除非此文档被加上一个%前缀；然后此文档将不能被链接，并且%标示被移除）
• 成员的链接在某一模式在文本中被建立时被创建。参考章节，学习更多如何自动化链接生成的工作信息。

作为LATEX输出的代价，在文本中的HTML 标识被中断并且被转换至LATEX