【原创】利用doxygen来管理项目文档或注释
以下先贴出我自己做出来的部分效果图，UI很挫，大家真正使用时可以让公司UI部门美化下，由于我目前还主要是内网使用，因此没有去过多考虑UI体验：
下载ubuntu14.04适用的doxygen源码。官网当中download选项里面有专门适用ubuntu的版本下载。下下来的源码包命名格式大致如：doxygen-{doxygen版本号}.src.tar.gz 解压。命令如下：
<span style="color: #0000ff;">gunzip</span> doxygen-$VERSION.src.<span style="color: #0000ff;">tar</span><span style="color: #000000;">.gz </span><span style="color: #0000ff;">tar</span> xf doxygen-$VERSION.src.<span style="color: #0000ff;">tar</span>
环境检查，要安装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的使用可以说就是对配置文件的配置，就是说，你只要稍微配置一下配置文件，再执行一下命令： xxxx/doxygen xxxx.conf 就可以生成你想要的文档（这里doxygen提供了多种格式的文档，我主要用的是html的，这样我们可以自己配置一个web服务到这个html上面，就可以再web上面使用文档了。），doxygen提供了200多个配置项，通过配置文件就已经可以完成丰富的功能了，下面举一些常用的配置说明：
XML_SCHEMA //XML模式设置（重要）
/** * @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页面上面。指定的管理人员定期的去查看下注释错误日志，即可即时纠正不对的注释内容。
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文件路径即可。
