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. 有.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 的安装路径。可以使用 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获取更多的如何自动化文档链接。
Doxygen 使用说明
Doxygen 是一个基于命令行的实用工具。在命令行使用—help可以显示关于各种命令的简短描述。
所有的命令开关都包括前导字符-, 后面跟什么命令(1 个字符或是多个字符)取决于你的选择。
为了为你的工程产生一个手册,典型的情况---- 你需要经过下面几个步骤:
1. 你想要在你的文档中使用特殊的块状标识 (请参考 Special documentation blocks章节)。
2. 可以通过使用doxygen 中的-g 来创建配置文件(请参考 Configuration章节):
doxygen -g <config_file>
4. 通过使用下面的命令来对你配置过的文件产生相应的文档:
doxygen <config_file>
doxygen -u <config_file>
如果你想让产生的文档能够按照某种你自定义的格式进行显示的话。如果你编辑了下面的内容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命令(后面跟上你想指定的文件名)。
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
配置
格式
一个配置文件是一个和Makefile有着类似结构的ASCII 文本文件,默认的配置文件名是Doxyfile。它是经doxygen分析后生成的。这个配置文件以固定的格式包含标记和新行 。配置文件中的设置是"大小写敏感"的。注释可以放在文档中的任何的位置(内部使用的"引号"除外)。注释采用的是以"#"开始的 单行注释形式。
文件中包含了很多"赋值语句"的形式。每条语句主要包含了一个后面跟着一个"="号的标志名TAG_NAME, 然后后面是1个或者多个值。如果相似的标志已经被多次的使用,那么最后使用的标志将会覆盖掉前面使用过的标志。下面列出了所有命令的列表,表中的" +=" 号 可以用来代替"=新值"。如果使用多个命令参数,它们之间是"不能有空格符"出现的。如果某个命令参数需要使用"空格符",则必须使用""把这个命令参数括起来。写成多行时,必须使用反斜杠 (/)做为该行的结束。环境变量可以通过使用$(ENV_VARIABLE_NAME)进行扩展。
想包含别的配置文件中的相关内容,只需使用下面格式的 @INCLUDE 标志即可:
@INCLUDE = config_file_name
被包含的文件通常先从当前路径搜索。你也可以通过使用路径指定自定义路径中被包含的配置文件。使用命令 @INCLUDE_PATH ,后面跟上被包含的配置文件的具体的路径,如下所示:
@INCLUDE_PATH = my_config_dir
配置选项可以被分成几类。下面给出的命令开关(或者说:配置选项)以字母顺序给出:
下面是需要涉及到的配置参数,通过对它们进行具体的设置能够实现想要的自定义效果.......
有些地方翻译的不太合适,请参照相关的链接来了解它所表示的意思........
通过用文本编辑工具打开通过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模式设置(重要)