Doxygen 配置详解

原創 Mourinho 2020-02-23 12:09

转自http://blog.csdn.net/skyremember/archive/2009/03/06/3964446.aspx

（翻译）Doxygen 配置详解（1）- -


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

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



                                           图：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标志的使用信息。

 

（翻译）Doxygen 配置详解（2）- -

注意：可以任意转载，但请注名出处

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

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

Doxygen 使用说明

Doxygen 是一个基于命令行的实用工具。在命令行使用—help可以显示关于各种命令的简短描述。
所有的命令开关都包括前导字符-， 后面跟什么命令（1个字符或是多个字符）取决于你的选择。
为了为你的工程产生一个手册，典型的情况----你需要经过下面几个步骤：
1.      你想要在你的文档中使用特殊的块状标识 (请参考Special documentation blocks章节)。
2.      可以通过使用doxygen 中的-g 来创建配置文件(请参考Configuration章节)：

doxygen -g <config_file>

3.      你需要针对你的工程编写相应的配置文件。在配置文件中你可以指定输入文件以及很多其它的信息。
4.      通过使用下面的命令来对你配置过的文件产生相应的文档：

doxygen <config_file>

如果你使用老版本的doxygen生成过配置文件，你可以通过运行doxygen 中的 -u 命令来对其进行更新。

doxygen -u <config_file>

在原来配置文件中的所有信息都会被替换成新的配置文件。所有新版本doxygen中的配置都会使用默认值。但是，你改动前的原来的配置文件中的所有的注释都会被自动删除。 
如果你想让产生的文档能够按照某种你自定义的格式进行显示的话。如果你编辑了下面的内容doxygen 能够帮你产生自定义的样式，头部显示内容，脚注形式：

  • 默认的情况下，HTML中会产默认的头部(请查看 HTML_HEADER获得更详细的信息)，默认的脚注 (请查看HTML_FOOTER获得更详细的信息)，默认的样式(请查看HTML_STYLESHEET获得更详细的信息)，需要用到的命令如下：
·       doxygen -w html header.html footer.html stylesheet.css
  • 想要产生 LaTeX 形式的输出格式，你可以创建refman.tex的第1部分 (请查看LATEX_HEADER获得更详细的信息)。同时，也可以在某个文件中加入下面的命令来丰富文档最终的头部显示样式：（下面是默认的2个文件）
·       doxygen -w latex header.tex doxygen.sty
  • 想要产生RTF形式的输出格式, 你可以创建一个默认的样式格式配置文件 (请查看RTF_STYLESHEET_FILE获得更详细的信息)：
·       doxygen -w rtf rtfstyle.cfg

注意:

  • 如果你不想对配置文件中的每一项都进行编制，你可以使用-s命令。通过与-u同时使用，可以实现在现存文档中增加或排除已存在的配置文件。如果你想向我报告BUG，请使用-s命令。

想要使用doxygen从键盘读/写信息而不是从输入/输出文件读写信息，你需要使用-for命令（后面跟上你想指定的文件名）。

 

（翻译）Doxygen 配置详解（3）- -

注意：可以任意转载，但请注名出处

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

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

Doxytag 使用说明

Doxytag 是一个基于命令行的小程序。它能够产生标志文件。这些标志文件能够被doxygen使用作为自己的标志文件。这些标志文件能够被用来为产生外部文档产生参考信息。 (例如：那些要被doxygen使用到，但是被包含在输入文件中的部分)。
一个标志文件包含关于这个文件中的classes，成员的相关信息。Doxytag能够直接从HTML文件中抽取这些信息。 这样就有了一个好处，不需要源代码就能够从doxytag中知道源代码到底有什么文件组成，每个文件的组成和它们的功能，以及文件之间的相互关系。
通过在doxygen中进行的配置文件中进行相应的配置，你能够很容易的在GENERATE_TAGFILE 之后放上相应的标志文件名。 
关键: 
如果你使用标志文件，通过doxygen生成links将会包含dummy（哑元）链接。你必须运行installdox脚本程序把这些dummy链接转化成真实的链接。请参考Installdox usage 章节获取更多的相关信息。Dummy链接看起来好象是没什么用处的，但实际上它非常的有用---如果你想要把外部文档移动到任何位置的的时候你会发现它很有用。只要你运行着installdox，文档不需要通过doxygen进行重新生成。
注意: 
因为，通常要在HTML文档中形成某种特定的结构，但是，通过doxygen生成的HTML文件中只有HTML或者是按照字母排序的classes视图形式。Doxytag只能读取HTML格式。 
Doxytag能够为一个在HTML目录下的所有的HTML文件建立标志。如果没有没有进行设置，Doxytag将从当前路径读取所有的扩展名为html的文件。 如果使用 doxytag中的-t命令就能生成一个标志文件。
例 1: 
假如下面列出的出现在examples目录下的example.cpp文件，以特殊块儿显示的文件形式，没有它的源文件。那么你就很幸运了，可以通过软件包中包含的分配器可以过doxygen生成包含HTML文档的文档形式显示的文件。

/** A Test class.

*  More details about this class.

*/


class Test

{

  public:

    /** An example member function.

     *  More details about this function.

     */

    void example();

};

 

void Test::example() {}

 

/** /example example_test.cpp

* This is an example of how to use the Test class.

* More details about this example.

*/

你只用使用下面的命令从HTML文件创建一个标志文件就能达到分析源文件由哪些部分组成，各个部分都是什么功能，以及它们之间有什么联系：

doxytag -t example.tag example/html

上面的examples是HTML文档原始的路径。这样，你就能在你自己的代码块儿中使用上面的标志文件了，如下所示照葫芦画瓢即可：

/*! A class that is inherited from the external class Test.

*/

 

class Tag : public Test

{

  public:

    /*! an overloaded member. */

    void example();

};

Doxygen能够为你的文档提供包含上所有指定过的链接选项。因为标志文件不能确定文档定位在哪里，你必须通过运行installdox脚本程序确定doxygen生成的文件放置到什么位置。(请参考 Installdox usage 章节获得更多的信息)。
注意：（不管你移动别人的文档或者是别人移动你的文档）把外部的文档移动到一个不同的路径下面或者改变链接设置，你只需简单的运行脚本就能实现所有连接的同步更新。 
点击 here 查看通过doxygen生成的相应的HTML文档和下面的第2个例子。 
例2: 
使用下面的命令行生成一个标记文档：

doxytag -t qt.tag $QTDIR/doc/html

翻译）Doxygen 配置详解（4）- -

注意：可以任意转载，但请注名出处

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

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

配置

格式

一个配置文件是一个和Makefile有着类似结构的ASCII 文本文件，默认的配置文件名是Doxyfile。它是经doxygen分析后生成的。这个配置文件以固定的格式包含标记和新行 。配置文件中的设置是"大小写敏感"的。注释可以放在文档中的任何的位置(内部使用的"引号"除外)。注释采用的是以"#"开始的 单行注释形式。
文 件中包含了很多"赋值语句"的形式。每条语句主要包含了一个后面跟着一个"="号的标志名TAG_NAME， 然后后面是1个或者多个值。如果相似的标志已经被多次的使用，那么最后使用的标志将会覆盖掉前面使用过的标志。下面列出了所有命令的列表，表中的" +=" 号 可以用来代替"=新值"。如果使用多个命令参数，它们之间是"不能有空格符"出现的。如果某个命令参数需要使用"空格符"，则必须使用""把这个命令参数 括起来。写成多行时，必须使用反斜杠 (/)做为该行的结束。环境变量可以通过使用$(ENV_VARIABLE_NAME)进行扩展。 
想包含别的配置文件中的相关内容，只需使用下面格式的 @INCLUDE 标志即可： 

@INCLUDE = config_file_name

被包含的文件通常先从当前路径搜索。你也可以通过使用路径指定自定义路径中被包含的配置文件。使用命令 @INCLUDE_PATH ，后面跟上被包含的配置文件的具体的路径，如下所示：

@INCLUDE_PATH = my_config_dir

配置选项可以被分成几类。下面给出的命令开关（或者说：配置选项）以字母顺序给出：

（翻译）Doxygen 配置详解（5）-----词汇表- -

下面是需要涉及到的配置参数，通过对它们进行具体的设置能够实现想要的自定义效果.......

有些地方翻译的不太合适，请参照相关的链接来了解它所表示的意思........

通过用文本编辑工具打开通过Doxygen生成的配置文件，然后用Ctrl+F来查找相关的"设置词汇"，来进行自定义，得到想要的文档显示格式

配置选项可以被分成几类。下面给出的命令开关（或者说：配置选项）以字母顺序给出：

配置选项可以被分成几类。下面给出的命令开关（或者说：配置选项）以字母顺序给出：

發表評論
所有評論
還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章

linux服务器监控

1.load load爲特定時間間隔內運行隊列中平均線程數。load average後面三個值代表1、5、15分鐘系統的load值，如果每個cpu的線程數大於5，表示系統負載較高，需採取措施降低負載，加快系統響應速度。 $ upti

公子 2020-07-08 10:30:45

记一次网站备案

用了幾個月的免費AWS，感覺非常好用，Amazon的技術實力確實一流，但是最近速度變得非常慢，也不知道是什麼原因，於是就買了阿里雲的雲主機，那就得備案啊。很多人都是談備案色變，論壇中也是一片罵孃的聲音，感覺我是在這麼一個恐怖的環境下開始的

newborn2012 2020-07-08 08:17:30

那些年我们一起敲过的机房收费系统——完结篇

引言    不知不覺，我在機房收費系統上耗的時間也有兩個月多了，很尷尬，就像我們的故事一樣，摻雜了太多感情在裏面了，但是地球總還是要轉的，明天早上太陽依然還是要升起的，所以這件事還是要有個完結的，所以今天我們就再此寫下此完結篇，臨表嗟嘆

bink_linda 2020-07-08 03:53:02

华为Mate30网络拒绝接入wifi问题 ，解决动态MAC白名单限制（新手机连接不了公司WIFI网络解决方法）

華爲Mate30網絡拒絕接入wifi問題 ，解決動態MAC白名單限制       由於公司對WIFI接入管控比較嚴格，路由器設置了MAC地址過濾，只允許白名單MAC地址接入，對於公司同事新入手華爲mate30 Pro 5G 的用戶，需要做

sunfor 2020-07-07 23:14:55

超声波指纹识别技术

前言： 2015年，整個超聲技術界最引人注目的事情莫過於高通推出了超聲波指紋識別技術Sense ID，而小米手機也成功搭載了這一項黑科技。自上世紀五十年代全國超聲熱之後，超聲技術終於有機會成爲大衆話題之一 超聲檢測技術基礎之基礎

liyongqi_ 2020-07-07 12:07:09

word使用过程中遇到的问题记录（二）：如何画柱状图和折线图的组合图？

最近在寫一些報告，要用到不少表格和圖，一開始不知道如何畫柱狀圖和折線圖的結合體，查了一番後搞定，記錄下，以備日後翻閱。 以GDP的數據爲例說明： 1、在word中插入一張柱狀圖表，會自動生成一個excel，用來填寫數據，如下圖所示： 根

芸轩 2020-07-07 00:53:20

【创业】华为那一套不是处处吃香

有2年了，幾個朋友都是華爲的，40上下，公司發展一般，心有不甘，談到創業，硬是找了個路子去做。2年下來，真是狗血劇。基本上把電視劇裏能想到的橋段都出現了。給朋友們一饗，提個醒，也算沒白乾。1)不要把創業代替就業我這兩年，感覺到周圍的朋友，

zhangling61130 2020-07-06 22:09:02

您适合从事web前端开发吗？

 隨着互聯網的迅猛發展和普及，一個新型的行業和新興的職位正在上升到技術的層面：web前端開發工程師。一些想從事、或感興趣的人會問：我適合做前端工程師嗎？什麼樣的人最合適？ 首先，我們看一下前端新人從哪裏來？相對於其他IT技術職位來說，

东方潮汐 2020-07-06 18:05:44

浅谈云计算的形态

 原文：淺談雲計算的形態 這幾年雲計算概念炒的很火熱，不僅是很多的雲計算相關的創業公司如雨後春筍般冒出來，大佬們也紛紛加入戰場。IaaS、PaaS、SaaS、BaaS多種形態並存，一派繁榮景象。本文結合自己的理解對目前市面上的雲計算形

东方潮汐 2020-07-06 18:05:34

sql server 不允许保存更改，您所做的更改要求删除并重新创建以下表 的解决办法

原文地址 啓動SQL Server Management Studio 工具菜單—-選項—-Designers(設計器)—-阻止保存要求重新創建表的更改 取消勾選即可。

诗人江湖老 2020-07-06 13:25:13

Timeout 时间已到。在操作完成之前超时时间已过或服务器未响应。 (.Net SqlClient Data Provider)

　　原文地址 　　在做一個小東西的時候出現了這個問題,就是使用VS調試幾次項目後,使用SQL Server Management Studio管理數據庫時,使用SA登錄就會出現這個錯誤,當然,如果項目中的數據庫連接字符串中使用的

诗人江湖老 2020-07-06 13:25:13

自然用户界面

自然用戶界面（英語：Natural user interface, NUI）是指一類無形的用戶界面。 “自然”一詞是相對圖形用戶界面（GUI）而言的，GUI要求用戶必須先學習軟件開發者預先設置好的操作，而NUI則只需要人們以最自然的交流方

Smile_路飞 2020-07-06 03:58:01

网站部署不成功——Win7 64位 IIS未能加载文件或程序集“System.Data.SQLite”或它的某一个依赖项

系統部署失敗。 原因：未能加載文件或程序集“System.Data.SQLite”或它的某一個依賴項 解決方案： 1、需要在IIS裏設置，設置應用程序池——啓用32位應用程序  把啓用32位應用程序的false改爲true2、下載 Sy

战神 2020-07-05 20:57:23

免费开源项目管理软件介绍

       現在開源的項目管理軟件可謂五花八門，很多人都不知道如何去選擇一個項目管理軟件。一個真正好的項目管理軟件，只能是針對自己要管理的內容來說的。很多時候我們看了那些軟件的介紹還是無從選取。下面我對比較流行的項目管理軟件用一個圖表來

战神 2020-07-05 20:57:23

一些知识收集

  C# String與byte[]之間轉換  http://developer.51cto.com/art/200908/148342.htm s

thebigbird 2020-07-05 17:01:03