Doxygen一个程序的文件产生工具
简介Doxygen
一.什么是Doxygen?
Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。
Doxygen 就是在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。
因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文档。
目前Doxygen可处理的程序语言包含:
· C/C++
· Java
· IDL (Corba, Microsoft及KDE-DCOP类型)
而可产生出来的文档格式有:
· HTML
· XML
· LaTeX
· RTF
· Unix Man Page
而其中还可衍生出不少其它格式。HTML可以打包成CHM格式,而LaTeX可以透过一些工具产生出PS或是PDF文档。
二.安装Doxygen
· 1.1 安装 Doxygen 1.7.4(Windows)
· 1.2 安装 graphviz 2.28.0(Windows)
graphviz 是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图,如不需要此功能可不安装该工具包。
· 1.3 安装 Windows Help Workshop 1.32
Doxygen 使用这个工具可以生成 CHM 格式的文档。
三.Doxygen的配置
Doxygen 产生文档可以分为三个步骤。一是在程序代码中加上符合Doxygen所定义批注格式。二是使用Doxywizard进行配置。三是使用Doxygen来产生批注文档。
Doxygen 1.7.4 主界面如下图 1 所示。
说明:1,Doxygen 工作目录,就是用来存放配置文件的目录。
2,递归搜索源文件目录需要选上。
选择 wizard 标签下的 Output Topics
相关配置说明如下图 2 所示。
选择 wizard 标签下的 Diagrams Topics
相关配置说明如下图 3 所示。
说明:如果选择这个选项之前需要先安装了 Graphviz 工具包。
选择 expert 标签下的 Project Topics
相关配置说明如下图 4 所示。
说明:编码格式,UTF-8 是首选。如果需要显示中文则选择GB2312.
TAB_SIZE 主要是帮助文件中代码的缩进尺寸,譬如@code和@endcode段中代码的排版,建议设置成4。
OPTIMIZE_OUTPUT_FOR_C 这个选项选择后,生成文档的一些描述性名称会发生变化,主要是符合C习惯。如果
是纯C代码,建议选择。
SUBGROUPING这个选项选择后,输出将会按类型分组。
选择 expert 标签下的 Build
Build页面,这个页面是生成帮助信息中比较关键的配置页面:
EXTRACT_ALL 表示:输出所有的函数,但是private和static函数不属于其管制。
EXTRACT_PRIVATE 表示:输出private函数。
EXTRACT_STATIC 表示:输出static函数。同时还有几个EXTRACT,相应查看文档即可。
HIDE_UNDOC_MEMBERS 表示:那些没有使用doxygen格式描述的文档(函数或类等)就不显示了。当然,如果EXTRACT_ALL被启用,那么这个标志其实是被忽略的。
INTERNAL_DOCS 主要指:是否输出注解中的@internal部分。如果没有被启动,那么注解中所有的@internal部分都
将在目标帮助中不可见。
CASE_SENSE_NAMES 表示:是否关注大小写名称,注意,如果开启了,那么所有的名称都将被小写。对于C/C++这种
字母相关的语言来说,建议永远不要开启。
HIDE_SCOPE_NAMES 表示:域隐藏,建议永远不要开启。
SHOW_INCLUDE_FILES 表示:是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列
表。
INLINE_INFO :如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明。
SORT_MEMBER_DOCS :如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显
示。
GENERATE_TODOLIST :是否生成TODOLIST页面,如果开启,那么包含在@todo注解中的内容将会单独生成并显
示在一个页面中,其他的GENERATE选项同。
SHOW_USED_FILES :是否在函数或类等的帮助中,最下面显示函数或类的来源文件。
SHOW_FILES :是否显示文件列表页面,如果开启,那么帮助中会存在一个一个文件列表索引页面。
选择 expert 标签下的 Input Topics
相关配置说明如下图 5 所示。
说明:输入的源文件的编码,要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。
总结:
我查看到我的代码文件是GB2312的(查看方法(以VS2008为例):文件->高级保存选项)。此时如果这里还是选择UTF-8,那么会导致编译出来的CHM文件中的中文会有乱码。
选择 expert 标签下的 HTML Topics
相关配置说明如下图 6 所示。
说明:1,CHM_FILE文件名需要加上后缀(xx.chm)。
2,如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项,此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。
3,为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码,CHM_INDEX_ENCODING中输入GB2312即可。
4,GENERATE_CHI 表示索引文件是否单独输出,建议关闭。否则每次生成两个文件,比较麻烦。
5,TOC_EXPAND 表示是否在索引中列举成员名称以及分组(譬如函数,枚举)名称。
选择 Run 标签
相关配置说明如下图 7 所示。
点击 Run doxygen 按钮, Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。
四.撰写正确格式的批注
并非所有程序代码中的批注都会被Doxygen 所处理。您必需依照正确的
格式撰写。原则上,Doxygen 仅处理与程序结构相关的批注,如
Function,Class ,档案的批注等。对于Function内部的批注则不做
处理。Doxygen可处理下面几种类型的批注。
JavaDoc类型:
/**
* ... 批注 ...
*/
Qt类型:
/*!
* ... 批注 ...
*/
单行型式的批注:
/// ... 批注 ...
或
//! ... 批注 ...
要使用哪种型态完全看自己的喜好。以笔者自己来说,大范围的注
解我会使用JavaDoc 型的。单行的批注则使用"///" 的类型。
此外,由于Doxygen 对于批注是视为在解释后面的程序代码。也就是
说,任何一个批注都是在说明其后的程序代码。如果要批注前面的程
式码则需用下面格式的批注符号。
/*!< ... 批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...
上面这个方式并不适用于任何地方,只能用在class 的member或是
function的参数上。
举例来说,若我们有下面这样的class。
class MyClass {
public:
int member1 ;
int member2:
void member_function();
};
加上批注后,就变成这样:
/**
* 我的自订类别说明 ...
*/
class MyClass {
public:
int member1 ; ///< 第一个member说明 ...
int member2: ///< 第二个member说明 ...
int member_function(int a, int b);
};
/**
* 自订类别的member_funtion说明 ...
*
* @param a 参数a的说明
* @param b 参数b的说明
*
* @return 传回a+b。
*/
int MyClass::member_function( int a, int b )
{
return a+b ;
}
当您使用Doxygen 产生说明文档时,Doxygen 会帮您parsing 您的程
式码。并且依据程序结构建立对应的文件。然后再将您的批注,依据
其位置套入于正确的地方。您可能已经注意到,除了一般文字说明外
,还有一些其它特别的指令,像是@param及@return 等。这正是
Doxygen 另外一个重要的部分,因为一个类别或是函式其实都有固定
几个要说明的部分。为了让Doxygen 能够判断,所有我们就必需使用
这些指令,来告诉Doxygen 后面的批注是在说明什么东西。Doxygen
在处理时,就会帮您把这些部分做特别的处理或是排版。甚至是制作
参考连结。
首先,我们先说明在Doxygen 中对于类别或是函数批注的一个特定格
式。
/**
* class或function的简易说明...
*
* class或function的详细说明...
* ...
*/
上面这个例子要说的是,在Doxygen 处理一个class 或是function注
解时,会先判断第一行为简易说明。这个简易说明将一直到空一行的
出现。或是遇到第一个"." 为止。之后的批注将会被视为详细说明。
两者的差异在于Doxygen 在某些地方只会显示简易说明,而不显示详
细说明。如:class 或function的列表。
另一种比较清楚的方式是指定@brief的指令。这将会明确的告诉
Doxygen,何者是简易说明。例如:
/**
* @brief class或function的简易说明...
*
* class或function的详细说明...
* ...
*/
除了这个class 及function外,Doxygen 也可针对档案做说明,条件
是该批注需置于档案的前面。主要也是利用一些指令,通常这部分注
解都会放在档案的开始地方。如:
/*! \file myfile.h
\brief 档案简易说明
详细说明.
\author 作者信息
*/
如您所见,档案批注约略格式如上,请别被"\" 所搞混。其实,"\"
与"@" 都是一样的,都是告诉Doxygen 后面是一个指令。两种在
Doxygen 都可使用。笔者自己比较偏好使用"@"。
接着我们来针对一些常用的指令做说明:
@file |
档案的批注说明。 |
@author |
作者的信息 |
@brief |
用于class 或function的批注中,后面为class 或function的简易说明。 |
@param |
格式为 @param arg_name 参数说明 主要用于函式说明中,后面接参数的名字,然后再接关于该参数的说明。 |
@return |
后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。 |
@retval |
格式为 @retval value 传回值说明 主要用于函式说明中,说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。 |
Doxygen 所支持的指令很多,有些甚至是关于输出排版的控制。您可从Doxygen的使用说明中找到详尽的说明。
下面我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式:
example.h:
/**
* @file 本范例的include档案。
*
* 这个档案只定义example这个class。
*
* @author garylee@localhost
*/
#define EXAMPLE_OK 0 ///< 定义EXAMPLE_OK的宏为0。
/**
* @brief Example class的简易说明
*
* 本范例说明Example class。
* 这是一个极为简单的范例。
*
*/
class Example {
private:
int var1 ; ///< 这是一个private的变数
public:
int var2 ; ///< 这是一个public的变数成员。
int var3 ; ///< 这是另一个public的变数成员。
void ExFunc1(void);
int ExFunc2(int a, char b);
char *ExFunc3(char *c) ;
};
example.cpp:
/**
* @file 本范例的程序代码档案。
*
* 这个档案用来定义example这个class的
* member function。
*
* @author garylee@localhost
*/
/**
* @brief ExFunc1的简易说明
*
* ExFunc1没有任何参数及传回值。
*/
void Example::ExFunc1(void)
{
// empty funcion.
}
/**
* @brief ExFunc2的简易说明
*
* ExFunc3()传回两个参数相加的值。
*
* @param a 用来相加的参数。
* @param b 用来相加的参数。
* @return 传回两个参数相加的结果。
*/
int ExFunc2(int a, char b)
{
return (a+b);
}
/**
* @brief ExFunc3的简易说明
*
* ExFunc3()只传回参数输入的指标。
*
* @param c 传进的字符指针。
* @retval NULL 空字符串。
* @retval !NULL 非空字符串。
*/
char * ExFunc2(char * c)
{
return c;
}
Doxygen一个程序的文件产生工具相关推荐
- Doxygen 一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件
Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C.C++.Java.Objective-C和IDL语言,部分支持PHP.C#.注释的语法与Qt-Doc.KDoc和J ...
- 发现一个程序员的好工具,方便的浏览器查阅资料
发现一个程序员的好工具,方便的浏览器查阅资料,加入qq群即可,群文件获取.,客服群QQ:336302800. 大家可以到群文件夹中下载工具,并且可以在QQ群中咨询和反馈建议.
- 解决“VMware另一个程序锁定文件的一部分,进程无法访问“的问题
昨天小区电路改造,整栋楼都断电了.今天打开VMware里的虚拟机cross2时,弹出"另一个程序已锁定文件的一部分,进程无法访问",如图(1)所示: 图(1) 虚拟机被锁定 ...
- 编写一个程序个人资料管理工具 考试题目 求大神帮忙 可以给一定报酬 万分感谢!
- 文件搜索工具(Python实现)
文章目录 文件搜索工具介绍 代码实现 实现思路 os.walk函数 os.path.join函数 代码整体编写 打包成exe程序 效果展示 文件搜索工具介绍 文件搜索工具能够基于名称快速定位匹配的文件 ...
- 微信小程序之 微信开发工具使用教程详解
如果你要开发自己的微信小程序或者小游戏,微信开发者工具是必不可少的,因为有些微信封装的方法只有微信开发者工具上才能使用,还有一个重要的原因就是,我们提交我们的代码审核必须通过该工具来提交,所有要做微信 ...
- gorm preload 搜索_8种最佳免费文件搜索工具
一个免费的文件搜索工具听起来确实像是一个免费软件可在您的计算机上搜索文件.这些免费文件搜索工具是可靠的程序,其中许多功能比计算机现在内置的搜索功能强大. 如果您一直习惯在计算机上命名和组织成百上千个( ...
- 如何高速拷贝超大文件?大文件拷贝工具Total Copy和Burst Copy
文件越来越大,硬盘空间也越来越大,但在拷贝和移动大文件时,你是否曾遇到过麻烦?是速度太慢?是经常出现操作失败?还是在操作期间消耗过多的系统资源使系统处于停滞状态?不必担心,仔细阅读本文后,以上种种问题 ...
- 文件对比工具(做软件版本)
1. 当需求分析,做完详细设计开发以后.我们就要开始为软件做版本,在原有的基础之上升级,还是增加模块开发 选择一个好的文件对比工具是必需的,这个工具支持文件,文件夹对比.可以大量提高软件的升级速度 这 ...
最新文章
- VTK:绘图之AreaPlot
- [BUUCTF-pwn]——ciscn_2019_n_3
- springboot点击运行没反应,什么都不显示的解决方式
- bash 与 dash
- Pandas时间差(Timedelta)
- oracle procedures批量删除带索引条件数据很慢_redis数据结构、持久化、缓存淘汰策略...
- 在实际项目中,如何选择合适的机器学习模型?
- ImportError: DLL load failed: 找不到指定的模块。Import tensorflow时
- Spring框架(下)JdbcTemplate、声明式事务管理
- KNN算法(10折交叉验证)
- JavaFX 2 Dialogs
- 一些图像置乱算法matlab
- 国内域名如何转入 GoDaddy,域名转入GoDaddy要注意?
- UE4 关闭屏幕显示信息响应
- 计算机文档字体替换,word2007进行字体替换的两种方法
- 2015美国计算机研究生就业,2015年美国计算机专业研究生排名
- 夜神模拟器 开发 重新连接
- 【speach】语音信号基础
- Android GCM使用
- 事务Read Committed (读已提交)和Repeatable Read(可重复读)到底什么区别?
热门文章
- 百度飞桨—PM2.5预测
- 时事评论----抑制楼市投机长痛不如短痛
- 免费顺丰快递鸟单号查询不限次数api接口申请步骤
- 游戏修改器制作教程一:键盘鼠标模拟
- zucc c语言上机答案,ZUCC第三章 习题答案.doc
- java 设置打印机颜色_java 操作颜色选择器和打印机实现打印功能【代码片段】...
- (SEED-LabCross-Site Scripting (XSS) Attack Lab跨站脚本攻击实验
- 【视频笔记】华中农业大学-分子生物学:P7-基因的结构 1
- 20176408李俊 类与对象
- 2020王者营地服务器维护,至尊宝重磅返场,王者营地服务器崩溃,只因玩家等待了五年的它...