如何使用Doxygen为C添加标准化注释

转载请注明出处http://blog.sina.com.cn/u/1580340211

自己之前没有注意我的代码规范，现在回过头去看简直一塌糊涂，决定以后规范自己的代码编写，尤其是注释部分，因为其对于代码重用十分重要，doxygen免费又方便，所以在学opencv的时候应该可以作为我规范化编码的首选工具。

【了解Doxygen】

       按照参考手册上说的，Doxygen目前可以支持的文档有C++，C，Javc，Object-c，Python，IDL，Fortran，VHDL，PHP。

        Doxygen可以产生以下三种主要类型文档：

· 1. It can generate an on-line documentationbrowser (in HTML) and/or an off-line reference manual from aset of documented source files. There is also support forgenerating output in RTF (MS-Word), PostScript,hyperlinked PDF, compressed HTML, and Unix man pages. Thedocumentation is extracted directly from the sources, which makesit much easier to keep the documentation consistent with the sourcecode.

· 2. You can configure doxygen to extract thecode structure from undocumented source files. This is veryuseful to quickly find your way in large source distributions. Youcan also visualize the relations between the various elements bymeans of include dependency graphs, inheritance diagrams, andcollaboration diagrams, which are all generatedautomatically.

· 3. You can also use doxygen forcreatingnormal documentation

以下是doxygen的信息流图：

       

【Doxygen注释规范】

        Doxygen使用一个配置文件来包含它的所有设定，每一个项目可以生成自己的配置文件，一个项目可以只含有一个单独的源文件，但是也会有一个能递归扫描的代码树。

        我选择采用文档中的JavaDoc风格的注释，主要需要的是如下的风格：

1        文档开头(包含两个“*”)

 

        PS：此时也可以使用QT风格的注释，也就是在C风格注释快开始处添加一个叹号‘！’

                           

2      简明描述和详细描述

        Doxygen在每个代码项中都可以有两类描述,这两类描述在文档中格式化在一起,一种是brief描述,另一种就是detailed。两种都是可选的，但是不能同时没有。（brief就是在一行内简述地描述，而详细描述则提供了更长，更详细的文档）

        这个部分在代码中有详细的说明，主要根据不同的需要来分类，不过主要还是使用默认的设置JavaDoc文档

3        前部注释和后部注释

前面提到的一般都是作为前部注释出现的，而doxygen的后部注释只需要在注释开始的双星号后面加上小于符号就可以了，类似于一个箭头指向被注释的代码。

 

【Opencv代码的Doxygen风格注释例子】

        因为自己现在本来就在弄图像处理的东西，就顺便注释一个最简单的视频读取代码作为练手

 

【如何运行Doxygen】

        一开始自己拿到的时候也是有点蒙，后来看了一下doxygen也是用工程的思想来组织文档的，当然内核还是使用xml来做为媒介，我为了方便就用了向导，如果有时间有精力有想法有信心可以自己用dos来指定……(此处我选择的是生成html这一最常用的帮助文档格式)

然后是设置各种参数（如果希望显示中文的童鞋不要忘记在语言部分选择Chinese，我第一次生成的就是各种乱码）

最后的最后，当然是运行啦，记住一定要英文路径啊，避免很多不必要的麻烦，我第一次没注意用的中文路径就木有成功啊：

        点击show HTML output按钮就可以在ie中显示自己定制的帮助文档了（原谅我盗了google的某天搜索封面图作为头图，这期太可爱了~）

还不赖哈哈

可以看到函数的定义已经成功生成了，因为自己是使用main函数作为例子，并且导出所有细节所以可以看到整个函数的内容，但是平时的帮助文档一般只导出brief和detailed说明而已，还有那些不知道是什么的圈圈叉叉就是使用中文的可怕后果啊！！！

 

 

 

经过一个下午的研究，基本搞懂doxygen生成文档的原理，也自己搞了个还可以看（虽然有很多乱码，呵呵）的html的C代码帮助文档，其实作为一个文档组织工具doxygen的功能远远强于此，以后会继续探索其在面向对象语言和泛型中的用法，当然还有自己正在学的python中也会用到它。

ps：虽然说实在吐槽无力，但是sina博客的排版功能就不能多点么，copy代码的时候难不成要自己写模块嵌入才行.....，竟然能够把注释真的注释了，害我要把代码弄成图片啊，碉堡了（汗⊙﹏⊙b汗）