文档生成工具-Doxygen使用方法以及注释规则
最近接触了一款程序 文档生成工具-Doxygen。在网上一搜索原来这么多人知道,打算把它的使用做一个总结,以及其注释的规则。
概述:
Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、Objective-C和IDL语言,部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始,生成HTML格式的在线类浏览器,或离线的LATEX、RTF参考手册。Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。
Doxygen 就是在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文档。
工具的准备
本人已经下载了这三个软件,打包后放在:点击打开链接
Doxygen下载
下载地址:http://www.onlinedown.net/soft/117010.htm
htmlhelp下载
如果你希望你的Doxygen自动生成chm,那么请下载HTML Help Workshop,我们将要使用当中的hcc.exe文件以及相关dll。 下载地址: http://msdn.microsoft.com/en-us/library/ms669985.aspx
Graphviz的下载
graphviz 是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图,如不需要此功能可不安装该工具包。
下载地址:http://www.skycn.com/soft/appid/6971.html
Doxygen工具的配置
在安装好开始配置Doxygen工具,运行Doxywizard。会出现以下界面
配置工作目录
点击Select选择自己的Doxygen的安装目录
配置Wizard选项卡
配置Project
首先修改Project name,选择扫描源代码的目录,Source code directory:,勾选Scan recursively (递归扫描),之后选择输出目录。
配置Model
在Wizard的Topics下的Mode,选择All Entities,可以输出相对完整的功能,是否包含源代码看你自身情况,在下面选择好你的语言。这里作者使用的是C++
配置Output
在Output中,如果你需要输出chm格式,请勾选。
配置Diagrams
在Diagrams中选择使用GraphViz包,来输出UML
配置expert选项卡
配置project
说明:编码格式,UTF-8 是首选。如果需要显示中文则选择GB2312.
TAB_SIZE 主要是帮助文件中代码的缩进尺寸,譬如@code和@endcode段中代码的排版,建议设置成4。
配置Build
Build页面,这个页面是生成帮助信息中比较关键的配置页面:
EXTRACT_ALL 表示:输出所有的函数,但是private和static函数不属于其管制。
EXTRACT_PRIVATE 表示:输出private函数。
EXTRACT_STATIC 表示:输出static函数。同时还有几个EXTRACT,相应查看文档即可。
SHOW_INCLUDE_FILES 表示:是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列表。
INLINE_INFO :如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明。
SORT_MEMBER_DOCS :如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显示。
配置Input
说明:INPUT_ENCODING (输入的源文件的编码),要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。
总结:我查看到我的代码文件是utf-8的(vs2013中打开文件 选另存为可看到编码格式)((VS2012的话):文件->高级保存选项)。
配置HTML
在Expert的HTML中,首先要看HHC_LOCATION选项,添加安装目录(注:作者目录为C:/Program Files (x86)/HTML Help Workshop/hhc.exe)
勾选CHM_INDEX_ENCODING,在你源代码中的字符集是什么就填写什么,
配置dot
之后在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK
为了减少chm体积,在DOT_IMAGE_FORMAT中选择gif或者jpg,均可。
最后选择好DOT_PATH所输出的位置。
Run选项卡
点击点击 Run doxygen 按钮, Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。
假如运行时遇到这个错误
Error: When enabling GENERATE_HTMLHELP the search engine (SEARCHENGINE) should be disabled. I’ll do it for you.
warning: The selected output language “chinese” has not been updated
since release 1.8.2. As a result some sentences may appear in English.
解决:把HTML里面的SEARCHENGINE设置为NO
到此chm文件生产完毕,为了下次代码调整后再次生产chm文件此时我们可以将目前所做的工作进行保存,点击File->Save,如下图:
后期使用可以通过步骤2中的file下的open菜单打开重新调整设置生产新的chm文件。好了Doxygen的安装与配置就讲到这里!
注释规范
以下是想使用doxygen工具生成程序文档需要在代码中遵守的注释规范(不全):
头文件模板:
/** @brief 这里写你的摘要
- @file 你的文件名
- @author 谁tmd的搞的
- @version 版本了
- @date 你啥时候搞的
- @note 注解. 例如: 本文件有什么具体功能啊,使用时要注意什么啊……
- @since 自从 例如: 自从2012年地球爆炸后这个文件就从地球上消失了……
*/
几句费话:
美中不足的是它没有修改历史记录. 我只能用@since来暂时代替它了.
除开始和结尾 中间 @前的*不是必须的,这里只是为了美观.
函数的注释:
/** 这里写这个函数是干什么用的
@param[in] 输入参数1
@param[in] 输入参数2
@param[out] 输出参数1
@return 返回值解释一下
@warning 警告: 例如: 参数不能为空啊,内存要外部释放之类的费话
@note 注解 随便你了
@see 相当于是请参考xxoo函数之类的
*/
费话:
这些东西并不是固定的你要哪几个就写哪几个.
关于返回值也可以这样搞
@retval 1 成功
@retval 0 失败
有时我们可能会写段示例代码在注释中这样搞:
在你的注释中加入这样的代码
@par 示例:
@code
extern IThread *pThread;
HANDLE hEvent = pThread->GetEventHandle();
while(WaitForSingleObject(hEvent,0) != WAIT_OBJECT_0)
{
//Do something
}
@endcode
还有几个你可能用上的东东:
@todo //我觉得这个描述算法比较好
@exception // 这个应该是用来说明你这个函数会抛出什么异常
@deprecated //这个函数可能在以后的版本中取消 所谓的什么过时列表
eg:
/** 构造函数
@param[in] pConfig 指向 TASKCONFIG 结构体的指针
@param[in] strWndName 目标窗口的名称, 如果此参数为空则不和任何窗口交互
@param[in] hRes 欲使用的资源句柄,如果参数为空则不使用资源
@warning pConfig 不能为空
@note 申请 pConfig 内存
@see IThread
*/
CThread_Plug(TASKCONFIG *pConfig,LPCTSTR strWndName,HINSTANCE hRes);
变量或者只有一行注解的东东,不超过一行的注释:
/**< 在这里写你要加的东西 */
OR
///< 在这里写你要加的东西
eg:
HINSTANCE m_hRes; ///< 要使用的资源句柄
CString _strWndName; ///< 目标接收消息的窗口名称
常用指令介绍
@file 档案的批注说明。
@author 作者的信息
@brief 用于class 或function的简易说明 eg:@brief 本函数负责打印错误信息串
@param 主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明
@return 描述该函数的返回值情况eg: @return 本函数返回执行结果,若成功则返回TRUE,否则返回FLASE
@retval 描述返回值类型 eg: @retval NULL 空字符串。@retval !NULL 非空字符串。
@note 注解
@attention 注意
@warning 警告信息
@enum 引用了某个枚举,Doxygen会在该枚举处产生一个链接 eg:@enum CTest::MyEnum
@var 引用了某个变量,Doxygen会在该枚举处产生一个链接 eg:@var CTest::m_FileKey
@class 引用某个类,格式:@class [] [] eg:@class CTest “inc/class.h”
@exception 可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
@todo 对将要做的事情进行注释
@see 一段包含其他部分引用的注释,中间包含对其他代码项的名称,自动产生对其的引用链接。
@relates 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since 通常用来说明从什么版本、时间写此部分代码。
@code 在注释中开始说明一段代码,直到@endcode命令。
@endcode 在注释中代码段的结束。
@pre 用来说明代码项的前提条件。
@post 用来说明代码项之后的使用条件。
@deprecated 这个函数可能会在将来的版本中取消。
@defgroup 模块名
@class 声明一个类
@fn 声明一个函数
doxygen的安装与注释规范就写到这里了,赶紧去试试吧!
转自:https://blog.csdn.net/Andy_93/article/details/53125776
文档生成工具-Doxygen使用方法以及注释规则相关推荐
- Swagger:后端文档生成工具
Swagger 在公司的项目中通常使用 swagger, 由后端来模拟业务数据. swagger 是一个 REST APIs 文档生成工具,它从代码注释中自动生成文档,可以跨平台,开源,支持大部分语言 ...
- APIDOC- API文档生成工具——node
文章目录 APIDOC apidoc拥有以下特点 apidoc安装使用 后端的代码需要给前端写一个接口文档. 可以自动生成. APIDOC apidoc是一个简单的RESTful API文档生成工具, ...
- Doxygen自动文档生成工具在Eclipse中的集成及使用举例
你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码 然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...
- 一款常用文档生成工具:Doxygen
关注+星标公众号,不错过精彩内容 来源 | 简书 编排 | strongerHuang 程序员的很多文档,特别是有代码的文档,绝大部分都是由一款文档生成工具[Doxygen]生成. 什么是Doxyge ...
- Doxygen文档生成工具
Doxygen代码文档生成工具 文章目录 Doxygen代码文档生成工具 Doxygen Doxygen的注释 vscode插件 Doxygen实际使用 Doxygen 根据百度百科说法,Doxyge ...
- python doc_Python文档生成工具pydoc使用介绍
在Python中有很多很好的工具来生成字符串文档(docstring),比如说: epydoc.doxygen.sphinx,但始终觉得pydoc还是不错的工具,用法非常简单,功能也算不错,本文主要介 ...
- .NET平台开源项目速览(4).NET文档生成工具ADB及使用
.NET平台开源项目速览(4).NET文档生成工具ADB及使用 原文:.NET平台开源项目速览(4).NET文档生成工具ADB及使用 很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习 ...
- java接口文档生成工具_接口文档生成
一.为什么要写接口文档? 1.正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的.一个工整的文档显得是非重要. 2.项目开发过程中前后端工程师有一个统一的文件进行沟通 ...
- java接口文档生成工具_【分享】接口文档生成工具apipost
一.为什么要写接口文档? 正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的.一个工整的文档显得是非重要. 项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发 ...
最新文章
- js中获得当前时间是年份和月份
- react+dva+antd接口调用方式
- Centos 配置JAVA_HOME
- ARM学习书单一提供打包下载地址
- 永恒传奇三服务器维护中,仙境传说ro3月3日5点-10点停服维护
- 6. 你必须掌握Dart中的数组
- java system_深入分析java中的System
- MyBatis中如何通过继承SqlSessionDaoSupport来编写DAO(二)
- BaaS后端即服务 - 概念篇
- 【Android】Listview返回顶部,快速返回顶部的功能实现,详解代码。
- 自定义标题栏右键菜单
- IntelliJ IDEA 12 中用 Maven + Jetty 来开发Web项目
- 删除VS工程下的临时文件
- mysql(一主从从)
- Word文档多级标题自动编号设置
- Final类型数据的初始化
- python建立窗口并美化_Python GUI教程(十六):在PyQt5中美化和装扮图形界面
- Java异常处理流程
- 6、Ordinary keyboard
- python统计文件中每个单词出现的次数_Python统计单词出现的次数
热门文章
- python预测糖尿病_实战 | 糖尿病预测项目
- DO、PO、VO、DTO、BO、POJO概念
- c语言中do是什么用法,C语言基础知识:do while用法理解
- Java 常用正则表达式,Java正则表达式,Java身份证校验,最新手机号码正则表达式...
- 《观止-微软创建NT和未来的夺命狂奔》 语录摘抄
- 解决ERROR 1819 (HY000): Your password does not satisfy the current policy requirements
- python字符串对象所有基本方法简要
- 老笔记本电脑机械500GB升级固态1T
- .NET Core部署到linux(CentOS)最全解决方案,高阶篇(Docker+Nginx 或 Jexus)
- 车载导航进阶「不输」手机,哪些供应商在领跑导航引擎赛道