Doxygen简单经验谈。。。

Doxygen, 大名鼎鼎的文档生成工具,被Boost、OpenCasCade等诸多项目作为文档生成的不二人选。人说,才华横溢往往是高深莫测,这句话放在 Doxygen这里显然是不适用的。十八般武艺样样精通的Doxygen,却十分的简单易用,从头到尾看一下它随机的文档,想不会用都难。。。
嫌看英文麻烦的,这里有一篇中文的入门介绍。 简单的说,如果你准备在项目中采用Doxygen作为文档生成的工具,首先,你需要了解,Doxygen需要什么样的代码结构才能够生产文档。 Doxygen基本上对光秃秃的代码不感兴趣,你需要在所有的类、函数、成员函数、公共变量、名字空间等代码已有表示的结构上方添加上指定格式的注 释,Doxygen才能识别出来。此外,你还可以按照指定格式的注释添加附加的信息,用以生成模块的分类,架构图之类的信息。Doxygen支持的注释格 式多种多样,强烈建议制定一个统一的标准,否则会给项目中其他的人员或者后来的人员带来很多的困扰。。。
按照指定的格式书写了注释之后,就需要写一个Doxygen的配置文件,依照此配置文件,Doxygen可以生产HTML、Tex、XML等多种格式输出 文档。Doxygen的配置文件,有辅助的GUI工具帮助书写,你只需要改几个选项,点几下按钮就信手拈来了。但在此强烈建议,你应该把Doxygen每 一个配置值的含义都了解一下,写一些简单的例子实践一下,这样一则你可以清楚的明白你需要的格式该如何配置出来,二则你可以充分了解Doxygen可以做 到什么程度,以备不时之需。。。
Doxygen通常是用作生成英文文档的,生成中文文档需要修改输入和输出的码制,这样可以改变解析方式,生成中文文档。但是,你必须意识 到,Doxygen在从注释中抽取信息是需要做语法解析的,这些解析都是基于英文的基础,不可能在这个层面上支持中文。比如,一个类的简明信息和详细信息 的分隔,是通过英文的句号“.”来识别的,如果你用中文的句号“。”,Doxygen就分辨不出来了。再比如,在某个类的注释中,你写 Created by xxx function,其中xxx是某个方法名,Doxygen会在生成的文档中,自动为该函数添加上链接。当如果你用中文:该类是被xxx方法构造出来的。 Doxygen就无法抽取出该信息并添上链接。你要按如下格式来写:该类是被 xxx 方法构造出来的。用强行的人肉空格帮助Doxygen。所有类似的问题都可以以此类推。。。
我们说,Doxygen无法识别光秃秃的代码信息,这并不意味着代码结构对Doxygen来说不重要。Doxygen可以对各种语言书写的代码进行优化, 比如你开启C++代码优化后,Doxygen会解析你写的C++代码,添加更多更具体的信息,并依照之间联系为你添加链接。这也就是说,Doxygen会 产生真实的代码结构表示出来的东西,你在写注释的时候也应该按照严谨的代码结构去写。比如,你在某个类A的注释中写道:此类用到了 B 类中的方法。假设B这个类,在名字空间N1内,如果,你的A类同样也是在N1内,这个链接Doxygen会为你自动添加,但是,如果B这个类在名字空间 N2内,Doxygen会无视你的请求。你必须严格的写它的全名 N2::A,Doxygen才会欣然接受这个娃。。。
我在做的项目比较小,因此我利用Doxygen的ToDo-List和Bug列表对项目进行简单的管理。比如,有一个类你有一些后续的工作没有完成,你可 以在其注释中加上@todo xxx,(这只是其中一种语法,不是唯一的规范...)Doxygen会将其链接添加到一个to do list中,并为该to do list生成一个页面,查看起来颇为方便。同样,Bug标记也是这么用这么看的,举一反三大家都会,我就不多磨叽了。。。
Doxygen中利用到很多第三方的基于编译的信息生成工具,辅助生成更为炫目的文档。比如,你可以在注释中嵌入符合tex标准的公式,Doxygen帮助你把这些显示到你的文档中来;你还可以为你的文档自动生成继承图,组合图,UML格式的图,等品种齐全的图,只要你把Graphviz装 上,并打开相关参数即可。更漂亮的是,利用Graphviz的dot方法,你可以将符合其格式的画图指令写在注释中,场景图,架构图,流图,交互图,隔壁 校长含泪跳楼图,只要你能用Graphviz画出,Doxygen都能给你用上,图例想改就改想变就变,幸福生活,不过尔尔。而关于Graphviz,g9老大已经推荐过 了,再多的好话也就显得苍白。这东西无疑是好东西,方便的一塌糊涂,对于常年和代码打交道对直观之物缺失判断的程序员而言,这无疑是居家旅行杀人必备的水 果刀。但要把水果刀玩的和关公大刀似的,是需要不俗功力的,像我这样三脚猫的功夫,就只能关注功能而无法挑战美观了。。。
其他的信息,比如author,date,group,之类的,我都会要求写注释的时候加上,举手之劳,可以方便很多后续可能出现的问题。每一个简单到无 需注释的函数,也要加一个空的注释头,以便生成文档的时候,所有的方法都齐备;如果有需要,你可以修改配置文件的设置,把代码也绑定进文档,这样别人只要 拿着文档一看,几乎就完全不用在添一份代码放在手上了。。。
把文档与代码绑定在一起,这是用Doxygen之类工具的一个好处,它至少可以产生两个方面的生产力。一方面,它可以帮助你构建结构良好的文档,生成真正 可看好看的文档来;另一方面,它可以刺激你更新文档,把文档工具当作项目管理工具用起来。当然,如果文档就在你写的代码上面两行你都懒的看一眼,那么,啥 工具也挽救不了了。用这类工具,必须要文档代码配合着写,配合着看,把它提升到和写单元测试一个习惯级别来,看一眼注释,写一段代码,然后测一测,改改过 期注释,就像蘸酱卷饼吃黄瓜一样一气呵成,那么,Doxygen就可以今夜做梦也会笑了。。。

posted on 2008-06-29 02:13 duguguiyu 阅读(...) 评论(...) 编辑 收藏

导航

统计