4     Doxygen配置文件

4.1   生成Doxygen配置文件

运行Doxywizard创建配置文件。
可以直接点“Save...”按钮,将保存默认的配置文件,名为Doxyfile,内容是Doxygen的默认设置。Doxyfile是普通文本文件,我们可以直接打开手动编辑。不过在Doxywizard的界面上填写也很方便,每个参数都有详细提示。建议用Doxywizard完成第一次设置。以后如果需要调整个别参数,可以直接编辑Doxyfile。

上述Doxywizard界面中提供了生成Doxygen文档的4个步骤,按照上述步骤一步步执行就可以生成漂亮的文档了。

第一步是生成配置文件,提供三种方式,Wizard方式指简约方式,在其中只提供一些重要的参数设置,其余的均为默认值;Expert方式为详细设置方式,通过该选项可以详细地配置Doxygen的各个配置项;最后一种是Load方式,用于导入以前生成的Doxygen配置文件,导入后可以再点击Expert进行修改。

4.2    配置选项含义详解

在上述界面中点击Expert按钮,或者用文本方式打开Doxyfile文件,可以看到Doxygen的参数配置项特别多,各个参数的含义其实也并不难掌握,在Doxygen的帮助手册中有详细的介绍,下面我介绍一些常用的参数含义,其余的参数大多可以设置为默认值。

DOXYFILE_ENCODING

Doxygen文件的编码方式,默认为UTF-8,若希望支持中文,最好设置为 GB2312

PROJECT_NAME

Project 的名字,以一个单词为主,多个单词请使用双引号括住。

PROJECT_VERSION

Project的版本号码。

OUTPUT_DIRECTORY

输出路径。产生的文件会放在这个路径之下。如果没有填这个路径,将会以目前所在路径作为输出路径。

OUTPUT_LANGUAGE

输出语言默认为English

EXTRACT_ALL

NO,只解释有doxygen格式注释的代码;为YES,解析所有代码,即使没有注释

EXTRACT_PRIVATE

是否解析类的私有成员

EXTRACT_STATIC

是否解析静态项

EXTRACT_LOCAL_CLASSES

是否解析源文件(cpp文件)中定义的类

INPUT

指定加载或找寻要处理的程序代码文件路径。这边是一个表列式的型态。并且可指定档案及路径。

FILE_PATTERNS

如果您的INPUT Tag 中指定了目录。您可以透过这个Tag来要求Doxygen在处理时,只针对特定的档案进行动作。例如:您希望对目录下的扩展名为.c, .cpp.h的档案作处理。您可设定FILE_PATTERNS = *.c, *.cpp, *.h    

RECURSIVE

这是一个布尔值的Tag,只接受YESNO。当设定为YES时,INPUT所指定目录的所有子目录都会被处理.

EXCLUDE

如果您有某几个特定档案或是目录,不希望经过Doxygen处理。您可在这个Tag中指定。   

EXCLUDE_PATTERNS

类似于FILE_PATTERNS的用法,只是这个Tag是供EXCLUDE所使用。

SOURCE_BROWSER

如果设定为YES,则Doxygen会产生出源文件的列表,以供查阅。

INLINE_SOURCES

如果设定为YES ,则函数和类的实现代码被包含在文档中

ALPHABETICAL_INDEX

如果设定为YES,则一个依照字母排序的列表会加入在产生的文件中。(有很多类、结构等项时建议设为YES

GENERATE_HTML

若设定为YES ,就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。

HTML_OUTPUT

HTML文件的输出目录。这是一个相对路径,所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html      

GENERATE_HTMLHELP

是否生成压缩HTML格式文档(.chm

HTML_FILE_EXTENSION

HTML文件的扩展名。预设为.html

HTML_HEADER

要使用在每一页HTML文件中的Header。如果没有指定,Doxygen会使用自己预设的Header

HTML_FOOTER

要使用在每一页HTML文件中的Footer。如果没有指定,Doxygen会使用自己预设的Footer

HTML_STYLESHEET

您可给定一个CSS 的设定,让HTML的输出结果更完美。

GENERATE_HTMLHELP

如设定为YESDoxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。

GENERATE_TREEVIEW

若设定为YESDoxygen会帮您产生一个树状结构,在画面左侧。这个树状结构是以JavaScript所写成。所以需要新版的Browser才能正确显示。

TREEVIEW_WIDTH

用来设定树状结构在画面上的宽度。

GENERATE_LATEX

设定为YES 时,会产生LaTeX 的文件。不过您的系统必需要有安装LaTeX 的相关工具。   

LATEX_OUTPUT

LaTeX文件的输出目录,与HTML_OUTPUT用法相同,一样是指在OUTPUT_DIRECTORY之下的路径。预设为latex                        

LATEX_CMD_NAME

LaTeX程序的命令名称及档案所在。预设为latex

GENERATE_RTF

若设定为YES ,则会产生RTF 格式的说明档。

RTF_OUTPUT

HTML_OUTPUT 用法相同,用来指定RTF 输出档案路径。预设为rtf

GENERATE_MAN

若设定为YES ,则会产生Unix Man Page 格式的说明文件。

MAN_OUTPUT

HTML_OUTPUT 用法相同,用来指定Man Page的输出目录。预设为man

GENERATE_XML

若设定为YES ,则会产生XML 格式的说明文件。

ENABLE_PREPROCESSING

若设定为YES ,则Doxygen 会激活C 的前置处理器来处理原始档。               

PREDEFINED

可以让您自行定义一些宏。类似于gcc 中的-D选项。

CLASS_DIAGRAMS

这个标记用来生成类继承层次结构图。要想生成更好的视图,可以从 Graphviz 下载站点 下载 dot 工具。Doxyfile 中的以下标记用来生成图表:

HAVE_DOT

如果这个标记设置为 Yesdoxygen 就使用 dot 工具生成更强大的图形,比如帮助理解类成员及其数据结构的协作图。注意,如果这个标记设置为 Yes<CLASS_DIAGRAMS> 标记就无效了

CLASS_GRAPH

如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes,就使用 dot 生成继承层次结构图

GRAPHICAL_HIERARCHY

设置为YES时,将会绘制一个图形表示的类图结构

 

上面的表格只是描述了一些常用的配置,需要更加详细的信息请参考Doxygen的帮助手册。


(由于文章字数限制,后面的内容见《Doxygen详细介绍(三)》)