Doxgen的使用

Doxgen是一个文档生成工具，一年前就注意了这个东西，只是一直没用，今晚闲着就把它捡起来，以后写完代码就用它了。

Doxgen就是从你的代码中提取注释来生成供用户使用的说明文档，文档可以是各种格式，如html、rtf、xml等，不过我刚刚只是试验了html，感觉很不错。

Doxgen很容易上手，不到两个小时的时间已经算初步掌握。利用Doxwizard GUI可以很方便的设置自己所需要的文档效果，设置完后保存为一个配置文件就OK了，这样还有一个好处就是一个项目组的人按照自己的规范设置好后，其他人只需要拷贝这个配置文件，在开发过程中若要生成文档看一下，那么在运行Doxywizard的时候加载它就可以统一了。

 

我的设置很简单：

1. 在Output中设置输出为html并选中复选框with frames and a navigation tree，这样生成的html文档就可以看到一个浏览树在左侧；

2. 将OUTPUT_LAGUAGE一项选为chinese，这样生成的文档就可以显示在代码注释中写的中文了。

3. 为了在生成的文档中Brief Description中方便的生成说明，我在配置文件中手动更改了JAVADOC_AUTOBRIEF一项，将其设为YES，我在DoxyWizard GUI中没有找到设置这项的界面，所以手动改了。更改这项的好处是从Ogre的代码和文档中发现的。

4. 最后只要设置好目录就OK了。

 

在自己写代码的注释方面：

1. 通常生成的文档是供用户看的，所以不需要用户看到的注释用“//”或“/*    */”来做，而需要用户看到的就用“///”或“/**     */”。而且一般需要用户看到的注释都是写在*.h文件中。

2. 注释写在对应的函数或变量前面。

3. 常用的注释方法：@remark 做评论，@par 用来对分段，@param 用来说明对函数参数做解释，@return 用来说明对函数返回值做解释。“///”用来做Brief  description，而“/**   */”用来做Detailed description，在将上面提到的JAVADOC_AUTOBRIEF设为YES后，则“/**   */”内第一个句号前的部分自动作为Brief description。

 

以后就可以用这个工具了，不过记得一年前看的时候感觉这个东西没有Linux下那个texi2html生成的文档好看，不管怎样这个很方便，以后先用着。还有很多功能或许自己以后用得着。

贴着刚刚生成的文档的图片上来，呵呵，成就感……