【原创】利用doxygen来管理项目文档或注释
一、doxygen应用场景:
doxygen可以用来管理目前主流的编程语言的注释而形成文档系统。(包括C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran等)。doxygen官网地址(http://www.doxygen.nl/)近来大部分时间花在api接口的维护上面,其中比较重要的一个环节就是你写的接口如何让调用者一目了然的理解用法。不管是内部无线服务端与客户端之间的配合,还是对外开放的API接口,都一样。花了几天时间尝试了下使用doxygen结合svn hook来管理接口文档还是很方便实用的。doxygen官网自己本身其实就是利用doxygen来做的,如果大家想要看更具体的效果,就可以直接参考http://www.doxygen.nl/。
以下先贴出我自己做出来的部分效果图,UI很挫,大家真正使用时可以让公司UI部门美化下,由于我目前还主要是内网使用,因此没有去过多考虑UI体验:
二、安装:
doxygen目前已经比较全面的支持了windows、mac ox、linux等主流系统。而且基本上使用于目前所有的主流编程语言。这里简要介绍下自己在ubuntu系统下面的源码编译安装过程。其余安装方法可以参考官网。
下载ubuntu14.04适用的doxygen源码。官网当中download选项里面有专门适用ubuntu的版本下载。下下来的源码包命名格式大致如:doxygen-{doxygen版本号}.src.tar.gz 解压。命令如下:
gunzip doxygen-$VERSION.src.tar.gz
tar xf doxygen-$VERSION.src.tar环境检查,要安装doxygen,在ubuntu下面需要部分依赖的支持。进入解压后的目录里面,里面有个./configure 的shell脚本。 执行命令:sh ./configure 进行安装环境检查,里面会列出一些你当前系统已经满足要求的 和缺少的依赖。在ubuntu下面你 可以简单的利用 sudo apt-get install xxxx(依赖名称),来逐个把缺少的依赖都装上。这步也很快的。
接下去就是、sudo make 和 sudo make install了。 如果在make或者 make install的过程中有提示缺少什么东西的话。sudo apt-get install xxx装上即可。
完事之后,在命令行下面试试看执行命令:doxygen --version 。 如果出来版本号,说明已经安装成功。
补充说明:关于make 和 make install。我个人比较喜欢直接make后使用源码包里面的 xxx/bin/doxygen 命令来生成文档, 而不去安装。 因为后期真正使用其来生成文档的时候会发现我们需要改掉里面很多默认的东西(当然不改也是完全可以的,并非不能用)。 这个时候你可以去找到刚才解压的源码包里面xxx/src/ 下面的源码文件,找到执行对应功能模块的.cpp文件(c++写的源码),你直接可以自己去修改里面的c++文件,然后重新用make编译。 这样就可以把doxygen改为任何你自己想要的效果。举个简单的例子:doxygen默认检查你代码后function都叫做函数。而在api接口中,我更希望一个function叫做一个接口,而不是叫做一个函数。 其他修改类似。
三、使用doxygen之配置文件的配置:
doxygen的使用可以说就是对配置文件的配置,就是说,你只要稍微配置一下配置文件,再执行一下命令: xxxx/doxygen xxxx.conf 就可以生成你想要的文档(这里doxygen提供了多种格式的文档,我主要用的是html的,这样我们可以自己配置一个web服务到这个html上面,就可以再web上面使用文档了。),doxygen提供了200多个配置项,通过配置文件就已经可以完成丰富的功能了,下面举一些常用的配置说明:
- 利用命令xxx/doxygen -g 就会在当前目录下面产生一个默认配置文件 doxygen.conf。打开默认配置文件,你会发现里面每一个配置项都是 配置名 配置值 这样的key-value格式,如果你有一定的英文功底的话,配置基本上就不是什么问题了。
- 配置的详细说明请参考:http://www.stack.nl/~dimitri/doxygen/manual/config.html
- 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 //类-图
- 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 //例子递归
- 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目标
- 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文件的简短描述
- 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模式设置(重要)
四、doxygen配置完成后注释的书写
当你配置好doxygen后,今后你基本上的时间都是花在你代码当中的注释的书写和维护。想要利用doxygen来管理文档。那么代码的注释就必需严格要求。
- 下面是我所用到的常用注释的书写要求,其他的更多请参考:http://www.stack.nl/~dimitri/doxygen/manual/commands.html
/**
* @brief 这里用brief来说明接口方法的主要功能
* @date 接口方法的创建时间
* @author 接口方法的创建人
* @param : 参数说明如下表:
* name | type |description of param
* ----------|-----------|--------------------
* car_id | int |车源编号
* province | int |业务员所在省份
* x | x | x
* x | x | x
* x | x | x
* @return 返回值说明如下:
* name | type | description of value
* -------- |----------|----------------------
* car_id | int | 车源编号
* car_info | object | json对象格式的车源信息
* @warning 该接口需要告知给调用者看的一些警告
* @attention 该接口需要告知给调用者看的一些注意事项
* @note 该接口的一些备注说明。通常用于当后者对该接口有较大改动的时候。备注一下某个时间点某人改动了什么东西
* @ todo 该接口的一些未完成的待办内容
*/
public function newSale() {
do someting;
}
按照规范书写注释后,在页面文档中展示的效果如下:
在项目内部可以提前约定好书写规则,余下的只要大家按照这个规则来维护即可。当然人毕竟是人,不可能保证所有的代码都能按照预期的注释规则书写。因此doxygen的配置文件里面可以指定日志文件的路径。你可以好好利用这个日子文件,用相应的脚本语言写一小段代码来分析这个日志文件,然后人性化点展示到web页面上面。指定的管理人员定期的去查看下注释错误日志,即可即时纠正不对的注释内容。
五、doxygen的比较常用的特性
markdown语法的使用,doxygen完美的支持所有markdown语法。你可以在注释中使用任何markdown语法。 也可以直接在项目doxygen配置文件中指定的INPUT路径下面书写md文件。你可以把如何使用文档?如何书写注释?等等一些公告内容用md文件来存放。这样,每个md文件就会再html文档系统里面独立生成一个页面。并在左侧形成一个独立的菜单。
别名的使用。利用配置文件里面的ALIASES可以设置注释别名,在书写注释的过程中,经常有些东西是必须写,而又一成不变的东西可以使用别名来简化。详见:http://www.stack.nl/~dimitri/doxygen/manual/custcmd.html
由于每次修改完代码后,都需要用doxygen命令来重新生成文档,文档才会更新。所以如果你的文档对实时性的要求比较高的话,可以考虑借助公司内部的版本管理系统的hook来实现。我使用的是svn hook里面的post-commit来实现,当程序员把自己书写的代码提交svn的时候,hook去自动重新执行doxygen命令来更新文档。这样就能做到文档的实时更新,而不需要我们码农去做什么。
生成后的文档系统的左侧菜单往往并非我们想要的结果。我们希望改为一些我们自己的连接或者我们自己的显示名称。这事可以利用配置文件里面的LAYOUT_FILE = DoxygenLayout.xml (名称可以自己定,这是默认名称)。 执行命令 doxygen -l 会在当前目录下面生成当前文档的默认layout文件DoxygenLayout.xml,打开编辑DoxygenLayout.xml里面的xml内容就可以改变左侧的菜单接口。具体自己研究了哈,这里不细说。
header.html 和 footer.html 页头和页尾的自定义。是否感觉生成的文档的界面并不那么的尽如人意,尝试自己写个页头和页尾。只是简单的html,首先你要获取到系统默认的header.html和footer.html,然后在默认的基础上面修改。获取默认header.html和footer.html和页面css的命令为:doxygen -w html new_header.html new_footer.html new_stylesheet.css YourConfigFile。
修改页面的样式,使其拥有更好的UI体验。可以使用配置文件中的 HTML_STYLESHEET 或者 HTML_EXTRA_STYLESHEET 来写自己的样式css文件或者扩展css文件。只需要在配置文件里面把两个配置指向你自己的css文件路径即可。
- 制作一个你自己的Logo图片,再把系统上面的按个默认的doxygen的logo给替换下就万事大吉了。替换logo使用配置项:PROJECT_LOGO 。
doxygen的功能还远远不止我上面介绍的那些,还有很多丰富多彩的功能,有想要使用这东西的人,可以自己去doxygen官网上面学习下哈。本文可随意转载,但是请务必注明原文出处。


【原创】利用doxygen来管理项目文档或注释的更多相关文章
- 通过VuePress管理项目文档(一)
VuePress 相关链接 完整的Vue组件代码以及完整的文档,仅适用于个人参考学习: 文档预览地址:预览链接 使用VuePress编辑文档的代码访问:组件文档 完整代码:组件代码 Vue组件开发 这 ...
- 通过VuePress管理项目文档(二)
通过vue组件实现跟:Element相似的效果.需要在VuePress网站中将自己的项目中的Vue组件运行结果展示在页面中. 至于如何将组件在VuePress网站中展示请参考:https://segm ...
- Git与GitHub学习笔记(六)使用 Github Pages 管理项目文档
前言 你可能比较熟悉如何用 Github Pages 来分享你的工作,又或许你看过一堂教你建立你的第一个 Github Pages 网站的教程.近期 Github Pages 的改进使得从不同的数据源 ...
- [课程分享]IT软件项目管理(企业项目甘特如是评价、维护管理、文档管理、风险管理、人力资源管理)
[课程分享]IT件项目管理(企业项目甘特图案例评价.维护管理.文档管理.风险管理.人力资源管理) 对这个课程有兴趣的朋友能够加我的QQ2059055336和我联系 课程讲师:丁冬博士 课程分类:Jav ...
- springboot项目利用Swagger2生成在线接口文档
Swagger简介. Swagger2是一款restful接口文档在线生成和在线调试工具.很多项目团队利用Swagger自动生成接口文档,保证接口文档和代码同步更新.在线调试.简单地说,你可以利用这个 ...
- PowerDesigner(九)-模型文档编辑器(生成项目文档)(转)
模型文档编辑器 PowerDesigner的模型文档(Model Report)是基于模型的,面向项目的概览文档,提供了灵活,丰富的模型文档编辑界面,实现了设计,修改和输出模型文档的全过程. 模型文 ...
- VS2010/MFC编程入门之二(利用MFC向导生成单文档应用程序框架)
VS2010/MFC编程入门之二(利用MFC向导生成单文档应用程序框架)-软件开发-鸡啄米 http://www.jizhuomi.com/software/141.html 上一讲中讲了VS20 ...
- 使用gitlab runner 进行CI(四):使用Gitlab Page托管项目文档
目录 1.什么是Gitlab Pages 2.开启Gitlab Pages 3.基本过程 4.托管markdown文档 4.1 安装sphinx等依赖 4.2 配置项目的sphinx配置 4.3 编写 ...
- Atitit. 项目文档目录大纲 总集合 v2
Atitit. 项目文档目录大纲 总集合 v2 -----Atitti.原有项目源码的架构,框架,配置与环境说明 v3 q511 -----Atitit.开发环境 与 工具 以及技术框架 以及 注意 ...
随机推荐
- Java度线程——生产消费问题
/*JDK1.4版本:生产者,消费者.多生产者,多消费者的问题.if判断标记,只有一次,会导致不该运行的线程运行了.出现了数据错误的情况.while判断标记,解决了线程获取执行权后,是否要运行! no ...
- ASPNET Core 部署 Linux — 使用 Jexus Web Server
第一步 安装.Net Core环境 安装 dotnet 环境参见官方网站 https://www.microsoft.com/net/core. 选择对应的系统版本进行安装.安装完成过后 输入命令查看 ...
- java编程思想-复用类(2)
如果java的基类拥有某个已被多次重载的方法名称,那么在导出类中重新定义该方法名称并不会屏蔽其在基类中的任何版本(这一点与C++不同) class Homer { char doh(char c) { ...
- [React] Use Prop Collections with Render Props
Sometimes you have common use cases that require common props to be applied to certain elements. You ...
- 加入收藏BUG改善
<script type="text/javascript"> function add_favorite(a, title, url) { url = url || ...
- 使用带粒子效果的 CAEmitterLayer
1.用CAEmitterLayer产生粒子效果 2.封装CAEmitterLayer 3.封装下雪.下雨的粒子效果控件 一.用CAEmitterLayer产生粒子效果 - (void)emitterL ...
- python模块之 paramiko(转载)
paramiko模块提供了ssh及sft进行远程登录服务器执行命令和上传下载文件的功能.这是一个第三方的软件包,使用之前需要安装. 1 基于用户名和密码的 sshclient 方式登录 # 建立一个s ...
- Linux操作系统改动PATH的方法
1. 暂时改动: 使用export.比如#export PATH=$PATH:/etc/apache/bin 2. 针对用户的改动: vi ~/.bash_profile 增加:export PATH ...
- ImportError: cannot import name _imaging
python - No module named 'PIL' - Stack Overflow https://stackoverflow.com/questions/49247310/no-mod ...
- from import 引入 变量 函数