【原创】利用doxygen来管理项目文档或注释

时间 2019-11-17

标签原创利用 doxygen 管理项目文档注释繁體版

原文原文链接

1、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体验：php

2、安装：

doxygen目前已经比较全面的支持了windows、mac ox、linux等主流系统。并且基本上使用于目前全部的主流编程语言。这里简要介绍下本身在ubuntu系统下面的源码编译安装过程。其他安装方法能够参考官网。

下载ubuntu14.04适用的doxygen源码。官网当中download选项里面有专门适用ubuntu的版本下载。下下来的源码包命名格式大体如：doxygen-{doxygen版本号}.src.tar.gz 解压。命令以下：css

gunzip doxygen-$VERSION.src.tar.gz 
tar xf doxygen-$VERSION.src.tar

环境检查，要安装doxygen，在ubuntu下面须要部分依赖的支持。进入解压后的目录里面，里面有个./configure 的shell脚本。执行命令：sh ./configure 进行安装环境检查，里面会列出一些你当前系统已经知足要求的和缺乏的依赖。在ubuntu下面你能够简单的利用 sudo apt-get install xxxx（依赖名称），来逐个把缺乏的依赖都装上。这步也很快的。html
接下去就是、sudo make 和 sudo make install了。若是在make或者 make install的过程当中有提示缺乏什么东西的话。sudo apt-get install xxx装上便可。java
完事以后，在命令行下面试试看执行命令：doxygen --version 。若是出来版本号，说明已经安装成功。linux
补充说明：关于make 和 make install。我我的比较喜欢直接make后使用源码包里面的 xxx/bin/doxygen 命令来生成文档，而不去安装。由于后期真正使用其来生成文档的时候会发现咱们须要改掉里面不少默认的东西（固然不改也是彻底能够的，并不是不能用）。这个时候你能够去找到刚才解压的源码包里面xxx/src/ 下面的源码文件，找到执行对应功能模块的.cpp文件（c++写的源码），你直接能够本身去修改里面的c++文件，而后从新用make编译。这样就能够把doxygen改成任何你本身想要的效果。举个简单的例子：doxygen默认检查你代码后function都叫作函数。而在api接口中，我更但愿一个function叫作一个接口，而不是叫作一个函数。其余修改相似。c++

3、使用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模式设置（重要）web

4、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页面上面。指定的管理人员按期的去查看下注释错误日志，便可即时纠正不对的注释内容。面试

5、doxygen的比较经常使用的特性

markdown语法的使用，doxygen完美的支持全部markdown语法。你能够在注释中使用任何markdown语法。也能够直接在项目doxygen配置文件中指定的INPUT路径下面书写md文件。你能够把如何使用文档？如何书写注释？等等一些公告内容用md文件来存放。这样，每一个md文件就会再html文档系统里面独立生成一个页面。并在左侧造成一个独立的菜单。shell
别名的使用。利用配置文件里面的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 。