Doxygen一些技巧

    团队的代码习惯一直不好，注释五花八门，甚至几千行代码没有一千行注释。几个新进来的成员纷纷抱怨，痛定思痛，决定来一次大刀阔斧的改变。

    由于本部门团队编写接口的时候比较多，做接口说明文档也是本分内的事情，既能规范注释，又方便编写文档，于是想到了Doxygen这个神器，也决定使用Doxygen的注释规范。

    说实话，几年前接触过这个东西，但仅仅玩了下就给扔掉了，并没有深入，这次玩发现不少有意思的东西。初级的东西咱们不说了，直接用doxywizard搞定，几个NEXT，配置文件就搞定了，一般的项目不在话下。这边有几个技巧倒是可以说说。

1.识别任意类型文件

    一般来说，Doxygen能够识别的代码类型和文件类型有限，如果是Doxygen能识别之外的文件类型，需要配置下EXTENSION_MAPPING这个参数。这个参数怎么设？直接上英文的说明有点不厚道，毕竟大家时间都有限，我就捏个关键的“The format is ext=language, where ext is a file extension, and language is one of the parsers supported by doxygen:IDL, Java, Javascript, C#, C, C++, D, PHP, Objective-C, Python, Fortran”，格式就是 扩展名=这些支持的语言。比方说，我有个文件ff.zaphx，Doxygen识别不到了，加上这个配置：

EXTENSION_MAPPING = zaphx=php

它就把这个ff.zaphx当PHP文件来解析了，更多的你也可以试试。

2.表格还有一些奇奇怪怪的东西

    Doxygen原生支持一些简单的表格，看这个示例：

/**
* Column1|Column2|Column3|Column4
* --|--|--|--
* Row1_content1|Row1_content2|Row1_content3|Row1_content4
* Row2_content1|Row2_content2|Row2_content3|Row2_content4
*/

跑下看看，是个漂亮的表格：

    有些人说没办法写历史记录，Doxygen好像没有生成文件历史记录的指令，还好有个标题文字可以用下，也蛮好用的

/**
* 标题
* --
* 这一节的内容
*/

看下效果：

也挺不错的，然后两个工具配合使用：

/**
 * @file file.name
 * @author 作者
 * @version 1.0.0.0
 * 
 * 更新历史
 * --
 * 版本号|说明|修订者|修订日期
 * ------|----|------|--------
 * v1.0.0.0|创建文档|作者|2016-10-08
 * 
 */

跑下Doxygen，见证奇迹的时刻：

相当漂亮，除了更新历史那边还有些别扭，比版本什么的都大一些。

我不是处女座，对我来说，这样就足够了，但这一点区别能把处女座憋屈死，怎么办？还有个杀手锏，直接使用html标签的指令htmlonly，看这个：

/**
 * @file test.auphx
 * @author 作者
 * @version 1.0.0.0
 * 
 * @htmlonly
 * <span style="font-weight: bold">更新历史</span>
 * @endhtmlonly
 * 版本号|说明|修订者|修订日期
 * ------|----|------|--------
 * v1.0.0.0|创建文档|作者|2016-10-08
 * 
 */

这次不骗你了，真的是奇迹来了：

效果妥妥的，不骗你。

还有一些WORD文档中常用的东西，比如这个点“ •”，表示一个项，Doxygen也同样有这个东西:

/**
* 论点的重要性
* --
* - 项目1
* - 项目2
*/

跑下看看：

玩多了Doxygen，简直停不下来有木有？

等我玩出 更多花来，还有内容奉送。