Doxygen文档系统
来源:互联网 发布:假期综合症 锻炼 知乎 编辑:程序博客网 时间:2024/05/17 00:52
1 序言
为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了程序的可维护性、可读性编码的同时写注释的说法,但对哪些地方应该写注释,注释如何写,写多少等这些问题,很多程序员仍然没有答案。更头痛的是写文档,以及维护文档的问题,开发人员通常可以忍受编写或者改动代码时编写或者修改对应的注释,但之后需要修正相应的文档却比较困难。如果能从注释直接转化成文档,对开发人员无疑是一种福音。而doxygen就能把遵守某种格式的注释自动转化为对应的文档。
Doxygen是基于GPL的开源项目,是一个非常优秀的文档系统,当前支持在大多数unix(包括linux),windows家族,Mac系统上运行,完全支持C++, C, Java, IDL(Corba和Microsoft 家族)语言,部分支持PHP和C#语言,输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目(如log4cpp和CppUnit)都使用了doxygen文档系统。
Doxygen 就是这样的一个工具。在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文件。
2 Doxygen及相关工具的下载
(1)Doxygen的最新版本,可以从Doxygen的网站下载。
(2)Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形,例如类的继承关系图、合作图,头文件包含关系图等。可以从Graphviz的网站下载Graphviz的最新版本。
3 Doxygen配置文件
3.1 生成Doxygen配置文件
运行Doxywizard创建配置文件。
可以直接点“Save...”按钮,将保存默认的配置文件,名为Doxyfile,内容是Doxygen的默认设置。Doxyfile是普通文本文件,我们可以直接打开手动编辑。不过在Doxywizard的界面上填写也很方便,每个参数都有详细提示。建议用Doxywizard完成第一次设置。以后如果需要调整个别参数,可以直接编辑Doxyfile。
上述Doxywizard界面中提供了生成Doxygen文档的4个步骤,按照上述步骤一步步执行就可以生成漂亮的文档了。
第一步是生成配置文件,提供三种方式,Wizard方式指简约方式,在其中只提供一些重要的参数设置,其余的均为默认值;Expert方式为详细设置方式,通过该选项可以详细地配置Doxygen的各个配置项;最后一种是Load方式,用于导入以前生成的Doxygen配置文件,导入后可以再点击Expert进行修改。
3.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,只接受YES或NO。当设定为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
如设定为YES,Doxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。
GENERATE_TREEVIEW
若设定为YES,Doxygen会帮您产生一个树状结构,在画面左侧。这个树状结构是以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
如果这个标记设置为 Yes,doxygen 就使用 dot 工具生成更强大的图形,比如帮助理解类成员及其数据结构的协作图。注意,如果这个标记设置为 Yes,<CLASS_DIAGRAMS> 标记就无效了
CLASS_GRAPH
如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes,就使用 dot 生成继承层次结构图
GRAPHICAL_HIERARCHY
设置为YES时,将会绘制一个图形表示的类图结构
上面的表格只是描述了一些常用的配置,需要更加详细的信息请参考Doxygen的帮助手册。
4 Doxygen的注释风格
4.1 综述
1) 文件头(包括.h和.cpp)
主要用于声明版权,描述本文件实现的功能,以及文件版本信息等
2) 类的定义
主要用于描述该类的功能,同时也可以包含使用方法或者注意事项的简要描述
3) 类的成员变量定义
在类的成员变量上方,对该成员变量进行简要地描述
4) 类的成员函数定义
在类定义的成员函数上方,对该成员函数功能进行简要描述
5) 函数的实现在函数的实现代码处,详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等
4.2 Doxygen支持的指令
4.2.1 概述
4.2.2 常用指令介绍
@brief
本函数负责打印错误信息串
@retval NULL
空字符串。
@retval !NULL
非空字符串。
4.3 JavaDoc风格的注释
4.3.1 概述
- /** description
- * description
- * description
- */
4.3.2 简述与详述的方式
- /*! @brief Brief description.
- * description continued.
- *
- * Detailed description starts here.
- */
- /** Brief description
- * description continued
- *
- * Detailed description starts here.
- */
- /** Brief description
- * description continued . (注意:这里有一个小数点,加上一个空格)
- * Detailed description starts here.
- */
4.3.3 文件头注释示例
- //////////////////////////////////////////////////////////////////////////
- /// COPYRIGHT NOTICE
- /// Copyright (c) 2009, 华中科技大学 (版权声明)
- /// All rights reserved.
- ///
- /// @file (本文件的文件名eg:Test.h)
- /// @brief (本文件实现的功能的简述)
- ///
- ///(本文件实现的功能的详述)
- ///
- /// @version 1.1 (版本声明)
- /// @author (作者,eg:卢俊)
- /// @date (文件创建日期,eg:2009年7月15日)
- ///
- ///
- /// 修订说明:最初版本
- //////////////////////////////////////////////////////////////////////////
4.3.4 类定义注释示例
- /** 本类的功能:打印错误信息
- *
- * 本类是一个单件
- * 在程序中需要进行错误信息打印的地方
- */
- class CPrintError
- {
- ……
- }
4.3.5 类成员变量定义示例
- /** 成员变量描述 */
- int m_Var;
- int m_color; /**< 颜色变量 */
4.3.6 成员函数的注释示例
- /** 下面是一个含有两个参数的函数的注释说明(简述)
- *
- * 这里写该函数的详述信息
- * @param a 被测试的变量(param描述参数)
- * @param s 指向描述测试信息的字符串
- * @return 测试结果 (return描述返回值)
- * @see Test() (本函数参考其它的相关的函数,这里作一个链接)
- * @note (note描述需要注意的问题)
- */
- int testMe(int a,const char *s);
4.3.7 枚举变量的注释示例
- /** 颜色的枚举定义
- *
- * 该枚举定义了系统中需要用到的颜色/n
- * 可以使用该枚举作为系统中颜色的标识
- */
- enum TEnum
- {
- RED, /**< 枚举,标识红色 */
- BLUE, /**< 枚举,标志蓝色 */
- YELLOW /**< 枚举,标志黄色. */
- }enumVar;
4.4 C++风格的注释
4.4.1 概述
4.4.2 简述与详述
- /// /brief Brief description.
- /// description continued.
- ///
- /// Detailed description starts here.
- ///
- /// Brief description
- /// description continued.
- ///
- /// Detailed description starts here.
- /// Brief description
- /// description continued . (注意:这里有一个小数点,加上一个空格)
- /// Detailed description starts here.
- ///
4.4.3 注释风格约定
1. 一个代码块(类、函数、结构等)的概述采用单行的”///”加一个空格开头的注释,并写在该代码块声明的前面;
2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释,若不足两行第二行的开头也要写出来,并且放在代码块定义的前面;如果某代码没有声明只有定义或者相反,则在定义或者声明前面写上单行的概述+一个空行+多行的详述;
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释;
4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释(相当于是给改变量一个概述);
5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面;
6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面;
7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面;
8. 文件头的版权以及文件描述的注释参见例代码。
4.4.4 文件头注释示例
- //////////////////////////////////////////////////////////////////////////
- /// COPYRIGHT NOTICE
- /// Copyright (c) 2009, 华中科技大学 (版权声明)
- /// All rights reserved.
- ///
- /// @file (本文件的文件名eg:Test.h)
- /// @brief (本文件实现的功能的简述)
- ///
- ///(本文件实现的功能的详述)
- ///
- /// @version 1.1 (版本声明)
- /// @author (作者,eg:卢俊)
- /// @date (文件创建日期,eg:2009年7月15日)
- ///
- ///
- /// 修订说明:最初版本
- //////////////////////////////////////////////////////////////////////////
4.4.5 类定义注释示例
- /// 本类的功能:打印错误信息
- ///
- /// 本类是一个单件
- /// 在程序中需要进行错误信息打印的地方
- class CPrintError
- {
- ……
- }
4.4.6 类成员变量定义示例
- /// 成员变量描述
- int m_Var;
- int m_color; /// 颜色变量
4.4.7 成员函数的注释示例
- /// 下面是一个含有两个参数的函数的注释说明(简述)
- ///
- /// 这里写该函数的详述信息
- /// @param a 被测试的变量(param描述参数)
- /// @param s 指向描述测试信息的字符串
- /// @return 测试结果 (return描述返回值)
- /// @see Test() (本函数参考其它的相关的函数,这里作一个链接)
- /// @note (note描述需要注意的问题)
- int testMe(int a,const char *s);
4.4.8 枚举变量的注释示例
- /// 颜色的枚举定义
- ///
- /// 该枚举定义了系统中需要用到的颜色/n
- /// 可以使用该枚举作为系统中颜色的标识
- enum TEnum
- {
- RED, ///< 枚举,标识红色
- BLUE, ///< 枚举,标志蓝色
- YELLOW ///< 枚举,标志黄色.
- }enumVar;
4.5 需要注意的问题
5 Doxygen使用的常见问题小结
5.1 中文问题:中文注释在文档中是乱码
5.2 图形问题:无法绘制类图协作图等图形。
5.3 输出chm的问题:如何输出.chm文件
5.4 Doxygen无法为DLL中定义的类 导出文档
- Doxygen文档系统
- Ubuntu系统使用Doxygen生成文档
- Doxygen文档
- DoxyGen文档之二
- DoxyGen文档三
- DoxyGen文档之四
- DoxyGen文档之五
- DoxyGen文档之六
- DoxyGen文档之七
- DoxyGen文档之八
- DoxyGen文档之九
- DoxyGen文档三
- Doxygen 文档注释详解
- Doxygen 文档注释详解
- 使用 doxygen 生成文档
- 程序文档与doxygen
- doxygen生成word文档
- doxygen 生成文档
- 如何学习安卓开发?
- hdu 3046 Pleasant sheep and big big wolf 网络流
- cocoaPods莫名其妙问题记录
- openstack nova基础知识——libvirt和qemu(2)
- 03/2010 Filezilla: Best ftp gui client for ubuntu
- Doxygen文档系统
- A. Kalevitch and Chess
- 指向学生类的指针
- Android开发之自定义dialog的实现(源代码分享)
- android studio gradle download 无反应
- yarn hadoop mapreduce 2.0 编译
- DCD DSR DTR RTS CTS表示什么意思
- Android 呼吸灯流程分析(一)
- UISegmentedControl-更改背景色和字体颜色