中文手册
v1.63 中文手册
DDDDoxygen
oxygen v1.63
中文手册中文手册
oxygen
oxygen
v1.63
v1.63
Anan
Anan
AnanAnan
-------------------------------- 【 声声声声 明明明明 】】】】 -----------------------------------
1. 此为免费文档,请勿用于商业用途。
2. 对于本手册的任何问题,请到各大专业论坛发问,我相信你会得到很多人的帮助。
-------------------------------- 【 约约约约 定定定定 】】】】 -----------------------------------
1. 对于意思不明确难以判断的句子,在给出的译文之后紧跟红色标记的原文 to get red origin text after
translated text 。
2. 对于省略的部分,即带有(略)字提示的部分,依旧会给出原文,以保证文档的完整性。
3. doxygen 配置文件中的选项标记一律使用蓝色提示。
4. 文中的内容备注一律使用橙色提示。
5. 对于文中所有的标题均用黑色粗体黑色粗体黑色粗体黑色粗体表示。
6. 文中的符号一律使用“”双引号标注,除去特别加入\“\”反斜杠表示转义之外,双引号无意义。
7. 文中的章节名称一律使用“”双引号粗体粗体粗体粗体标注,所以与符号不存在冲突。
8. 原文的错误一律使用绿色提示,并在译文之后给出,错处用下划线标注。
9. 文中所有的备注,使用“**”开头以及
深红色 进行标识。
-------------------------------- 【 问题问题问题问题】】】】 -----------------------------------
-------------------------------- 【 正文正文正文正文 】】】】 -----------------------------------
此手册被分为三个部分,每个部分都包含若干章节。
第一部分是用户指南
1. 安装安装安装安装,讨论如何在你的平台中下载,编译和安装 doxygen。
2. 开始开始开始开始,告诉你如何快速生成第一个 doxygen 文档。
3. 代码文档化
代码文档化,演示代码被文档化的若干方法。
代码文档化
代码文档化
4. 列表列表列表列表,,,,显示创建列表的若干方法。
5. 组合组合组合组合,显示如何将一些工作组合在一起。
6. 包含公式包含公式包含公式包含公式,显示如何在文档中插入公式。
7. 图形和图表
图形和图表,描述 doxygen 生成图表和图形。
图形和图表
图形和图表
8. 预处理预处理预处理预处理,解析 doxygen 如何处理宏定义。
9. 生成自动生成自动生成自动生成自动链链链链接接接接,显示如何在文档中放置文件,类,成员的链接。
10. 输出格式输出格式输出格式输出格式,显示如何生成 doxygen 支持的多种输出格式。
11. 搜索搜索搜索搜索,显示在 HTML 文档中进行搜索的若干方法。
12. 自定义输出
自定义输出,解析如何在 doxygen 中生成自定义的输出。
自定义输出
自定义输出
13. 自定义命令
自定义命令,显示如何在你的注释中定义和使用自定义的命令。
自定义命令
自定义命令
14. 连接到外部文档
连接到外部文档,解析如何让 doxygen 创建与外部已生成文档的链接。
连接到外部文档
连接到外部文档
15. FAQFAQFAQFAQ,对频繁出现的提问给出的回答。
16. 排错排错排错排错,当出现问题时,它会告诉你该做些什么。
第二部分是参考指南
1. 特点特点特点特点,展示 doxygen 的功能概览。
2. doxygen
doxygen 历史历史历史历史,告知 doxygen 在开发过程中的变化,以及它一直在进行的内容。
doxygen
doxygen
3. doxygen
doxygen 用法用法用法用法,告知如何使用 doxygen。
doxygen
doxygen
4. doxytag
doxytag 用法用法用法用法,告知如何使用 doxytag。
doxytag
doxytag
5. doxywizard
doxywizard 用法用法用法用法,告知如何使用 doxywizard。
doxywizard
doxywizard
6. installdox
installdox 用法用法用法用法,告知如果你使用 tag 文件,在 doxygen 中如何使用生成的 installdox 脚本。
installdox
installdox
7. 配置配置配置配置,告知如何调整 doxygen,以便生成你需要的文档。
8. 特殊命令字
特殊命令字,告知在文档中能使用的特殊命令的概览。
特殊命令字
特殊命令字
9. HTMLHTMLHTMLHTML 命令字命令字命令字命令字,告知在文档中能使用的 HTML 命令的概览。
10. XMLXMLXMLXML 命令字命令字命令字命令字,告知在文档中能使用的 C#风格的 XML 命令的概览。
第三部分为 doxygen 开发者提供的一些信息(略)
1. doxygen
doxygen 内部构造内部构造内部构造内部构造,给出 doxygen 内部结构的整体概览。
doxygen
doxygen
2. PerlPerlPerlPerl 模块的输出格式
模块的输出格式,显示如何使用 PerlMod 的输出。
模块的输出格式
模块的输出格式
3. 国际化国际化国际化国际化,解析如何添加新语种的输出支持。
安安安安 装装装装
如果你还没有 doxygen 程序包,首先可以去 http://www.doxygen.org/download.html 页面获得最新的版本。
本章节包含以下几部分:
Unix 源码包编译
Unix 二进制包安装
Unix 已知的编译问题
Windows 源码包编译
Windows 二进制包安装
Doxygen 开发工具(略)
Unix
Unix 源码包源码包源码包源码包编译编译编译编译
Unix
Unix
如果你已下载了源码包,你需要按照以下的步骤来创建可执行文件:
1. 需要 GNU 工具软件,flex,bison,GNU make,strip
2. 为了生成 Makefile,你需要安装 Perl。
3. 配置脚本已假定标准的 Unix 工具,例如 sed,date,find,uname,mv,cp,cat,echo,tr,cd,rm 都是
可用的。
想获得 doxygen 的所有功能,以下的辅助工具必须安装。
1. QT 4.3 或者更高版本,用于创建 GUI 后端 doxywizard。
2. 一个 OCR 种类的发布程序,比如 teTex 1.0,用于生成 LaTex,Postscript,PDF 的输出。
3. Graph visualization toolkit 1.8 或者更高版本,doxygen 中的 graphs, graphical inheritance graphs,
collaboration graphs 与 graphviz 都存在依赖关系,如果你准备重新编译 graphviz,确认系统是否支持
freetype,否则 graphs 无法渲染特殊文本的标记。
4. 如 果 需 要 显 示 公 式 , 并 且 你 不 想 使 用 pdflatex , 那 么 ghostscript 也 是 必 须 的 , 你 可 以 在
www.ghostscript.com 找到它。
5. 为了生成 doxygen 自身的文档,需要 Python,你可以在 www.python.org 找到它。
执行以下的步骤进行编译:
1. 解压程序包
gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive
tar xf doxygen-$VERSION.src.tar # unpack it
2. 运行配置脚本
sh ./configure
此脚本尝试检测你所使用的平台,make(必须是 GNU make),以及 Perl,并且脚本会输出检测结果。
你可以运行以下命令来配置,使用检测出的平台和编译器来替换掉命令中的 platform-type。
configure –platform platform-type
比对一下程序包中 PLATFORMS 文件所列出的平台与命令中的 platform-type。
如果系统中存在 QT 4.3 或者更高的版本,并需要创建 GUI 后端,要运行配置脚本的--with-doxywizard 选项,
configure --with-doxywizard
其他的配置选项的概览可以使用,
configure --help
3. 运行 make 编译程序
make
如果程序编译无任何问题,在系统的 bin 目录下将会有三个二进制可执行文件,doxygen,doxytag,doxywizard。
4. 生成用户手册
make docs
让 doxygen 生成 HTML 文档,在系统中的 HTML 目录下将包含此文档(目录中的 index.html 文件将指向一个 HTML
浏览器),此时你将需要 python 的支持。
5. 生成一个 PDF 版本的用户手册(此时你需要 pdflatex,makeindex,egrep 的支持)
make pdf
doxygen_manual.pdf 将放置在系统的 latex 目录下,可以使用 acrobat reader 查看和打印。
6. 安装 doxygen
make install
Unix 二进制包
Unix
二进制包安装安装安装安装
二进制包二进制包
Unix
Unix
如果你下载的是一个 Unix 的二进制发行版本,输入:
./configure
Make install
可执行的二进制文件将被安装到
/bin 目录下,使用 make install_doc 安装 doxygen 的文档和例子,安
装目录为/doxygen。
默认路径为/usr/local, 可使用配置脚本的--prefix 选项来修改安装的默认路径。
默认路径为/share/doc/packages,可是使用配置脚本的--docdir 选项来修改默认路径。
当然你也可以直接复制 doxygen 二进制文件,到/bin 或者 PATH 变量中能被检索到 bin 目录下,这一点对使用
doxygen 很重要。
注意注意注意注意::::
你需要 GNU 安装工具来完成上述的工作(这只是所需支持程序包的一部分),而其他的安装支持工具有可能被放
置到错误的目录下,请确认!如果你使用的是一个 RPM 或者 DEP 软件包,请遵照这些安装包的标准安装过程进行。
Unix 已知的编译问题
Unix
已知的编译问题
已知的编译问题
Unix
Unix
已知的编译问题
Qt 的问题
一些系统中 Qt 的头文件和库文件不在 QTDIR 所指向的目录下(比如 Red Hat 6.0,头文件路径/usr/include/qt,
库文件路径/usr/lib)。
解决方法:
进入 doxygen 的根目录,
mkdir qt
cd qt
ln -s your-qt-include-dir-here include
ln -s your-qt-lib-dir-here lib
export QTDIR=$PWD
如果你使用 C 风格的 shell,可用 setenv QTDIR $PWD 来替换 export 那一行。
Bison 问题
Bison 1.31~1.34 版本都存在一个编译错误:
ce_parse.cpp:348: member `class CPPValue yyalloc::yyvs' with constructor not allowed in union
这个问题已经 1.35 版本得到解决(1.31 之前的版本也不存在问题)。
Latex 问题
a4wide.sty 文件不是在所有的系统都有效,如果你的系统无法使用,请选择配置文件中其他的页
面类型(查看配置文件的 PAPER_TYPE 标记下的相关信息)。
HP-UX & Digital Unix 问题
如果你使用 aCC 在 HP-UX 中编译,会得到这个错误:
/opt/aCC/lbin/ld: Unsatisfied symbols:
alloca (code)
你可根据 Anke Selig 的提示,用 #include
替换掉 ce_parse.cpp 文件的以下部分,
extern "C" {
void *alloca (unsigned int);
};
如果没有任何帮助,尝试删除 ce_parse.cpp 文件,重新安装 bison 软件包。
如果在 Digital Unix 下编译,相同的问题可根据 Barnard Schmallhof 提示,在 ce_parse.cpp 文件中,使用
#else /* not GNU C. */
#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi) || defined (__osf__)
#include
替换掉以下内容,
#else /* not GNU C. */
#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi)
#include
还需要修正 bison 的一个问题,以下是 bison.simple 文件的 patch(由 Andre Johansen 提供)
--- bison.simple~ Tue Nov 18 11:45:53 1997
+++ bison.simple Mon Jan 26 15:10:26 1998
@@ -27,7 +27,7 @@
#ifdef __GNUC__
#define alloca __builtin_alloca
#else /* not GNU C. */
-#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi)
+#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi) || defined (__alpha)
#include
#else /* not sparc */
#if defined (MSDOS) && !defined (__TURBOC__)
此 patch 能在 doxygen 创建过程生成 scanner.cpp 文件。
Sun 编译问题
如果使用 Sun C++ WorkShop 6 编译器,出现 doxygen 无法正常工作的问题,我自己也不能确定真正的原因,我还
没有获得操控一台 Solaris 主机和编译器的途径。但是使用 GNU 编译 doxygen 是可以工作的,并且安装 Sun patch
111679-13 可以修正这个问题。
当配置时添加--static 选项,可以得到:
Undefined first referenced
symbol in file
dlclose /usr/lib/libc.a(nss_deffinder.o)
dlsym /usr/lib/libc.a(nss_deffinder.o)
dlopen /usr/lib/libc.a(nss_deffinder.o)
手动添加 -Bdynamic 在 Makefile.doxygen 和 Makefile.doxytag 文件的 target rule 之后,如下:
$(TARGET): $(OBJECTS) $(OBJMOC)
$(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic
GCC 编译问题
老版本的 GNU 编译器存在常量字符串的字符编码大于 127 的问题,并且在编译 translator_xx.h 文件时会出错,
如果你只准备使用英文字符,配置脚本中使用--english-only 选项可以规避以上的问题。
在一些平台(例如 OpenBSD)中,某些 gcc 版本在使用-O2 参数编译文件(比如 config.cpp)期间会产生内存泄漏,
配置脚本中使用--debug 选项或者删除掉 Makefile 中出错文件的-O2 编译参数,来规避内存泄漏。
因为存在 bug,Gcc 2.95 之前版本都可以终止二进制文件的执行。Gcc versions before 2.95 may produce broken
binaries due to bugs in these compilers.
Dot 问题
因为图元 image maps 生成方法的改变,老版本的 doxygen(<=1.2.17)无法与新版本的 graphviz(>=1.8.8)一同正
常工作。这种不兼容的结果导致 HTML 中生成 graphs 无法正常点击。推荐使用 doxygen 1.3 版本匹配 graphviz 1.8.10
或者更高的版本。推荐使用 doxygen 1.4.7 版本匹配 graphviz 2.8 或者更高的版本,以避免字体的问题。
Red Hat 9.0 问题
如果你运行 make 之后,得到以下的错误,
tmake error: qtools.pro:70: Syntax error
在运行 make 之前,输入 export LANG=
Windows
Windows 源码包源码包源码包源码包编译编译编译编译
Windows
Windows
从 1.5.0 版本开始支持 Visual Studio 2005 创建程序,当然免费的“专业”版本开发环境也能用来编译 doxygen。
或者安装 Cygwin 或 MinGW 采用 Unix 的方式进行编译。
编译 doxygen 之前需要下载和安装 visual studio 的 c++编译器,自从微软开始明显地诱惑所有人吸食他们的.net
毒品之后,他们使得运用专业版本时的难度增加了,所以你需要手动完成一些步骤,来定制一个合适的工作环境,
编译一个原始的 win32 应用程序,比如 doxygen。
http://msdn2.microsoft.com/en-gb/express/aa700755.aspx
配置 vs2005 的 win32 环境
下一步安装 unxutils,http://sourceforge.net/projects/unxutils ,此软件包囊括了 flex 和 bison 工具,
它们在编译处理时是必须的,如果你使用的是一个 doxygen 的 CVS,在官方的发行版本中包含有此软件包。下载 zip
文件并将其放置到,例如 C:\tools\unxutils 目录下.
现在你需要增加和调整系统的环境变量,
1. 增加 C:\tools\unxutils\usr\local\wbin 目录到 PATH 中
2. 添加变量 BISON_SIMPLE,为其设定 C:\tools\unxutils\usr\local\share\bison.simple 目录。
下载 doxygen 的源码包,放置到任意位置,比如 C:\tools
打开命令行界面,输入
cd c:\tools
gunzip doxygen-x.y.z.src.tar.gz
tar xvf doxygen-x.y.z.src.tar
解压源码包,现在环境被安装好了,可以创建 doxygen 和 doxytag。
进入 doxygen-x.y.z 目录,将会找到一个 winbuild 目录中包含一个名为 Doxygen.sln 文件,在 visual studio 打