Doxygen配置（翻译）

来源:http://dev.csdn.net/article/63/63284.shtm

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

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

 

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

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

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

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

 

 

 http://www.stack.nl/~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标志的使用信息。
 

 

 

 

 

来源:

http://shanzy.bokee.com/793962.html

 

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

                                      

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

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

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

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

 

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

ABBREVIATE_BRIEF                //简短摘要

ALIASES                                //别名

ALLEXTERNALS                      //所有外部文档

ALPHABETICAL_INDEX              //字母顺序索引

ALWAYS_DETAILED_SEC            //详细描述部分

BINARY_TOC                        //二进制操作

BRIEF_MEMBER_DESC              //简短的成员描述

CALL_GRAPH                       //调用到的图

CASE_SENSE_NAMES              //检测的范例的名字

CHM_FILE                          //CHM格式文件

CLASS_DIAGRAMS                 //类-表

CLASS_GRAPH                         //类-图

COLLABORATION_GRAPH          //相互调用关系图

COLS_IN_ALPHA_INDEX           //以列形式显示的字母顺序的索引

COMPACT_LATEX                  //压缩的LATEX文档

COMPACT_RTF                    //压缩的RTF文档

CREATE_SUBDIRS                //创建一个"子目录"

DETAILS_AT_TOP                 //文档的详细头部

DIRECTORY_GRAPH                  //目录图

DISABLE_INDEX                      //禁用INDEX

DISTRIBUTE_GROUP_DOC       //禁用文档成组显示

DOT_IMAGE_FORMAT            //点阵图形

DOT_MULTI_TARGETS           //多个DOT目标

DOT_PATH                            //DOT路径设置

DOT_TRANSPARENT                //DOT转换设置

DOTFILE_DIRS                      //DOTFILE 列表显示

ENABLE_PREPROCESSING      //允许"预处理"指令

ENUM_VALUES_PER_LINE      //每行的枚举值

ENABLED_SECTIONS           //允许分段显示

EXAMPLE_PATH                     //例子路径

EXAMPLE_PATTERNS            //例子用的文件格式（*.cpp, *.h , *.java等）

EXAMPLE_RECURSIVE             //例子递归

EXCLUDE                             //可执行文件

EXCLUDE_PATTERNS           //可执行文件格式（*.exe, *.dll等）

EXCLUDE_SYMLINKS              //可执行的SYMLINKS

EXPAND_AS_DEFINED             //规定的扩展

EXPAND_ONLY_PREDEF        //预定义扩展

EXTERNAL_GROUPS              //使用到的外部的文件

EXTRA_PACKAGES                //使用到的外部插件包

EXTRACT_ALL                      //提取所有

EXTRACT_LOCAL_CLASSES      //提取所有本地类

EXTRACT_LOCAL_METHODS   //提取所有本地方法

EXTRACT_PRIVATE                 //提取所有private

EXTRACT_STATIC                  //提取所有static

FILE_PATTERNS                     //文件路径

FILE_VERSION_FILTER            //文件版本控制

FILTER_PATTERNS                  //控制格式（主版本：第1次版本：第2次版本号）

FILTER_SOURCE_FILES           //原文件的版本控制

FULL_PATH_NAMES               //全路径名

GENERATE_AUTOGEN_DEF      //生成自动定义文件形式

GENERATE_BUGLIST              //生成BUG列表

GENERATE_CHI                     //生成"希腊字母"

GENERATE_DEPRECIATEDLIST //生成"评估"列表

GENERATE_HTML             //生成HTML

GENERATE_HTMLHELP            //生成HTMLHELP

GENERATE_LATEX                 //生成LATEX

GENERATE_LEGEND                //生成图例

GENERATE_MAN                    //生成MAN文件

GENERATE_PERLMOD        //生成Perl脚本

GENERATE_RTF                     //生成RTF  

GENERATE_TAGFILE               //生成标志文件

GENERATE_TESTLIST       //生成TESTLIST

GENERATE_TODOLIST            //生成TODOLIST

GENERATE_TREEVIEW          //生成树状视图显示

GENERATE_XML                    //生成XML 

GRAPHICAL_HIERARCHY          //继承图表

GROUP_GRAPHS                    //组-图

HAVE_DOT                          //隐藏DOT

HHC_LOCATION                    //隐藏位置

HIDE_FRIEND_COMPOUNDS  //隐藏"复合的"友员类型

HIDE_IN_BODY_DOCS            //隐藏文档的主体

HIDE_SCOPE_NAMES        //隐藏"作用域"名

HIDE_UNDOC_CLASSES          //隐藏"未归档"的所有CLASS

HIDE_UNDOC_MEMBERS         //隐藏"未归档"的所有的成员

HIDE_UNDOC_RELATIONS //隐藏"未归档"的关系

HTML_ALIGN_MEMBERS          //HTML文档中成员对齐方式

HTML_FOOTER                     //HTML脚注设置

HTML_HEADER                      //HTML头部设置

HTML_OUTPUT                     //HTML输出设置

HTML_STYLESHEET               //HTML样式设置

IGNORE_PREFIX                    //忽略哪些前缀

IMAGE_PATH                  //图片的路径设置

INCLUDE_GRAPH              //包含-图

INCLUDE_PATH                     //头文件包含的路径

INHERIT_DOCS                     //文档的继承关系

INLINE_INFO                  //内联信息

INLINE_INHERITED_MEMB   //通过"继承"得到的内联成员

INLINE_SOURCES                  //内联部分的源代码

INPUT                                 //输入设置

INPUT_FILTER                      //能够接受的输入文件的扩展名格式设置（重要）

INTERNAL_DOCS             //内部文档

JAVADOC_AUTOBRIEF            //JAVADOC工具生成的文档的"自动摘要"

LATEX_BATCHMODE               //LATEX匹配方式

LATEX_CMD_NAME                //LATEX 命令名

LATEX_HEADER                     //LATEX 头部

LATEX_HIDE_INDICES            //LATEX内部隐藏的包含

LATEX_OUTPUT                    //LATEX输出

MACRO_EXPANSION              //宏展开设置（重要）

MAKEINDEX_CMD_NAME         //MAKEINDEX命令索引

MAN_EXTENSION                  //MAN扩展

MAN_LINKS                          //MAN 链接设置

MAN_OUTPUT                      //MAN输出设置

MAX_DOT_GRAPH_DEPTH //DOT图的最大深度

MAX_DOT_GRAPH_HEIGHT      //DOT图的最大高度

MAX_DOT_GRAPH_WIDTH       //DOT图的最大宽度

MAX_INITIALIZER_LINES   //最大初始化行

MULTILINE_CPP_IS_BRIEF       //多 个CPP文件的简短描述

OPTIMIZE_OUTPUT_FOR_C     //对C采用的优化设置

OPTIMIZE_OUTPUT_JAVA //对JAVA采用的优化设置

OUTPUT_DIRECTORY        //输出路径设置（重要）

OUTPUT_LANGUAGE              //输出语言设置（重要）

PAPER_TYPE                        //纸张类型

PDF_HYPERLINKS                  //PDF格式超链接设置（重要）

PERL_PATH                          //perl路径设置

PERLMOD_LATEX             //perlmod LATEX

PERLMOD_PRETTY                 // perlmod PRETTY（漂亮/相当）

PERLMOD_MAKEVAR_PREFIX  //perlmod MAKE文件版本 PREFIX

PREDEFINED                    //预先定义（重要）

PROJECT_NAME                     //工程名（重要）

PROJECT_NUMBER                  //工程的组成成员（重要）

QUIET                                 //静态量设置（重要）

RECURSIVE                           //递归和循环

REFERENCED_BY_RELATION   //交叉参考（重要）

REFERENCES_RELATION           //交叉参考的关系

REPEAT_BRIEF                       //重新设置"简短说明"为打开状态

RTF_EXTENSIONS_FILE           //RTF展开文件

RTF_HYPERLINKS                   //RTF超链接

RTF_OUTPUT                        //RTF输出设置

RTF_STYLESHEET_FILE           //RTF样式文件

SEARCH_INCLUDES                 //搜索时需要包含什么（重要）

SEARCHENGINE                      //搜索引擎设定（重要）

SHORT_NAMES                      //使短文件名生效

SHOW_DIRECTORIES         //显示目录

SHOW_INCLUDE_FILES            //显示包含文件（一般NO，否则太大）

SHOW_USED_FILES                //显示被用到的文件（一般YES）

SKIP_FUNCTION_MACROS        //跳过函数中的宏（重要），菜鸟最好别跳

SORT_BRIEF_DOCS                //文档的简短摘要

SORT_MEMBER_DOCS             //成员的简短描述

SOURCE_BROWSER                 //原文件浏览路径

STRIP_CODE_COMMENTS  //排除哪些条码形式注释（重要）

STRIP_FROM_INC_PATH          //排除哪些头文件包含的注释（重要）

STRIP_FROM_PATH                //排除哪些条码路径设置

SUBGROUPING                       //子组设置（重要）

TAB_SIZE                             //TAB符SIZE设置（重要）

TAGFILES                             //标志文件

TEMPLATE_RELATIONS            //模板关系设置（重要）

TOC_EXPAND                        //TOC扩展

TREEVIEW_WIDTH                 //树状图显示的宽度设置（重要）

UML_LOOK                            //UML外观设置（重要）

USE_WINDOWS_ENCODING   //使用windows系统的编码形式（重要）

VERBATIM_HEADERS         //VERBATIM头部（头文件）

WARN_FORMAT                     //警告格式指定（重要）

WARN_IF_DOC_ERROR            //如果文档出错则显示警告

WARN_IF_UNDOCUMENTED   //如果是未归档文件则显示警告

WARN_LOGFILE                     //警告日志文件设置

WARN_NO_PARAMDOC            //无参数文档警告形式设定

WARNINGS                           //警告设置（重要）

XML_DTD                             //XML文件类型定义（重要）

XML_OUTPUT                        //XML输出设置（重要）

XML_PROGRAMLISTING           //XML程序列表（重要）

XML_SCHEMA                        //XML模式设置（重要）

 

本文来自CSDN博客，转载请标明出处：http://blog.csdn.net/yaosan/archive/2009/02/06/3866943.aspx