Doxygen简单经验谈。。。

Doxygen简单经验谈。。。

转自 http://www.cnblogs.com/duguguiyu/archive/2008/06/29/1231852.html

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就可以今夜做梦也会笑了。。。

=================================================================

doxygen生成rtf/word使用小心得

转自 http://hi.baidu.com/connyzone/blog/item/762c9cce9d2fe634f9dc6161.html

硕士毕业要写个技术文档，蒙了，真麻。怎么也都不行，后来老师给指了条路：使用doxygen。       网上有许多关于使用doxygen的帖子，不过大都是互相copy(怎么和我的名字很像，我可不是这样的人)，再不就是知而不言，言而不尽。不过我觉得来自CSDN的一篇文章很好，是伐木大哥的：使用doxygen为C/C++程序生成中文文档（上），找了好久，就是没有找到(下)，可能是他比较忙的原因吧，不过足以让我学一阵儿的了。(还是CSDN的技术贴和博客解渴)         网络上其他地方的叙述多是照搬伐木大哥的，今天我也不是要重新叙述一遍，而是讲讲我的心得。        目的：应用doxygen生成rtf/word格式文件。(网上大多是生成chm的，伐木大哥的也是，我在这里就算补充吧)        心态：虽然doxygen这一套东西弄下来(包括graphviz等)很麻烦，不过软件终究是软件，他不是编程软件，所以我们只是用它们帮忙生成个图或文档，没啥难的，别着急，静下心慢慢来。        不足：我只会生成英文的，中文的还在学习中(这点就比不上伐木大哥啦*^_^*)        第一步：摆平Wizard.                   Project标签：设置你的工程名(Project name)、版本号(ID)、源文件文件夹(Source code directory)、目标文件夹(Destination directory)                    mode标签：选语言啊，别忘了，别的没啥。                   Output标签：我这里是生成rtf/word的，就不勾HTML和LaTeX了。                   其他默认。         第二步：搞定Expert.                   许多朋友是卡在这里了。                   Project标签：其和Wizard的差不多，语言我选的是English，DOXYFILE_ENCODING默认为UTF-8。                   Messages标签：WARN_LOGFILE最好设置上，比如类似Error.log等，优秀的程序员调试程序的能力最强啦，这个WARN_LOGFILE恰恰类似于编程当中的Error，其包含了提示出错问题。                    Input标签：如果源程序按功能进行了分类，放置于不同文件夹，则需要添加不同文件夹路径。不过这种方法容易出问题，也麻烦，建议把所有源文件放置于同一目录下。毕竟我们只要生成的技术文档，这里的INPUT源代码只是用一用，用完可以删除。DOXYFILE_ENCODING默认为UTF-8。                    Source Browser标签：将SOURCE_BROWSER勾选上，其他默认。                    Index标签：可选填，因为这个是为了生成ftf/word的目录用的，如果你没把握弄好，在word里改也可以，而且选项更丰富。                     HTML+LaTex标签：两个标签都取消第一个框的勾选，因为我们是要生成rtf/word。                    RTF标签：勾选上第一个框，RTF_OUTPUT选择你想输出到的目录。                    Dot标签：将UML_LOOK勾选上，可以生成UML类关系图，其余勾选项选上最好。分别是模板(TEMPLATE)、调用(CALL)、被调用(CALLER)图，这样不是更方便吗，所以建议勾选。同时，在安装了graphviz前提下(务必先安装，用于生成UML图)，在DOT_PATH中，添加graphviz的bin目录。         第三步：保存一下吧，休息，休息一会.                    点击Step2下的Save，保存一下，不然以后要是有啥事，你刚才的工作白做了可别怪我。         第四步：快到了，看到终点线了(directory).                           设置Working directory(工作目标)，选择源代码的根目录，主要是因为配置的一些选项中有的可以用相对路径，这个就可以作为相对路径的参照点。         最终步：Start吧，新的开始.                     终于结束了，我的程序较大，生成了10秒多呢，心情激动啊。这只能是告一段落，让我们歇口气，不然为啥最后一步的按钮叫“Start”呢，呵呵，准备新的任务，新的开始，出发吧！