Doxygen 使用札记

• 简介

Doxygen 是一款开源的项目文档自动生成工具，类似的软件还有很多，如NDoc等。对于开发C++的项目，Doxygen可能是比较好的选择（NDoc主要针对.NET平台吧，没有仔细研究，不过doxygen也可以支持C#，所以还是直接用一个吧）。原因有2：
 - 比较Popular
 - 现在还持续更新着，意味着有维护
 - 开源免费

• 几个资源：

  - 主页：http://www.doxygen.org or http://www.stack.nl/~dimitri/doxygen/
  - 下载：http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc  目前最新版：1.5.7.1 (200810.5)
  - GraphViz： http://www.graphviz.org/  可用作内嵌类图绘制工具

• 基本使用

  用户和Doxygen的交互是通过一个配置文件的设置来完成的，用户可以用文本编辑器来编辑一个配置文件，也可以用图形界面工具Doxygen Wizard来配置。配置好后，把这个文件交给Doxygen，他就会生成相应的输出啦。输出格式包括：html, chm(间接支持）,PDF 等

• 注释

   要使Doxygen自动生成注释，我们必须要按照一定的格式来添加注释，而且还要使用一些Doxygen命令来说明注释中的参数。Doxygen可以支持几种不同风格的注释：JavaDoc风格，QT风格 etc。 Java是最流行的语言之一，所以在注释风格上，选择了JavaDoc风格（有例外）。下面是一个JavaDoc风格的多行注释：
rel="File-List" href="file:///C:%5CDOCUME%7E1%5Cryang%5CLOCALS%7E1%5CTemp%5Cmsohtml1%5C01%5Cclip_filelist.xml">

1. /**
3.  * … Comments …
5.  */

   它以"/**"作为注释的开始标志，以"*/"作为结束标志，中间的"*"为可选。 注释的第一行可以被用来作为Doxygen的Brief Description，条件是后面有空格或者换行符作为结束，再之后是详细注释。Doxygen的这个做法有时候容易让人搞糊涂，JavaDoc是强制实行注释中的第一句作为Brief。Doxygen有个选项(JAVADOC_AUTOBRIEF)，可以像JavaDoc那样来处理Brief Description。另外一个指定Brief的方法是使用Doxygen命令(/brief)
   单行的注释为

1. /**  Comments  */

    注释通常都是放在源代码的前面，如果要注释和源代码在同一行上，需要在注释开头追加一个"<"。如：

1. int iCount;  /**< The total number of students */

    另外，对于单行的注释，倾向于用C++风格的"///"，这样据说要比"/** */"美观一些。（来自于一位牛牛的意见）

• Doxygen命令

    Doxygen用一组命令来区分注释中的各种参数，如：brief description, parameter, author etc.
    下面这个例子演示了如何给一个函数作注释：

1. /** @brief A plus function.
2.   * 
3.   * This method pluses a with b.
4.   * @param a The first number
5.   * @param b The second number
6.   * @return The sum result
7.   */
8. int MyPlusFunc(int a, int b);

    上面例子中用到了三个Doxygen命令：brief, param and return。
    下面给出几个常用的Doxygen命令：    rel="File-List" href="file:///C:%5CDOCUME%7E1%5Cryang%5CLOCALS%7E1%5CTemp%5Cmsohtml1%5C01%5Cclip_filelist.xml">

 

        --File

We MUST add comment at the beginning of file for the file

We SHOULD use multiple lines comment, like:

/** @file 
   
   

 *  This file includes definition of test class. A more elaborate class description.
   
   

 *  
   
   

 *  @author Your name
   
   

 */
   
   

 

       --Class

We MUST add comment before the class definition.

We SHOULD use multiple lines comment, like:

/**
   
   

 * Brief description. Detailed description that can
   
   

 * be on many lines.
   
   

 */
   
   

       --Field

For comment field, you may choose add comment before or after, multiple lines or single line base on your circumstances.

char* fQuestion; ///< the question
   
   

int fAnswer;           //*< the answer */
   
   

 

         -- Method

We MUST add comment before method definition; we SHOULD NOT add comment to method declaration. That means if we declare a method in .h file and define it in .cpp file, we should not add comments in .h file for it, instead we should add comment in .cpp file.

We SHOULD use multiple lines comment, like:

/** A useful method.
   
   

  * 
   
   

  * This method does unbelievably useful things.  
   
   

  * And returns exceptionally useful results.
   
   

  * Use it everyday with good health.
   
   

  * @param level an integer setting how useful to be
   
   

  * @return Output that is extra useful
   
   

  */
   
   

void* VeryUsefulMethod(bool level);
   
   

 

        --Commands

We recommend you use below doxygen’s commands if you need.

Item	Commands
General	todo bug see remarks code example
File	file date author
Method	param exceptions return retval

 

• GraphViz

       默认情况下，Doxygen采用内置的画图工具来生成类的相关视图。用户也可以选择用第三方的画图工具GraphViz来画图，相关的设置项为HAVE_DOT。
    GraphViz采用一种结构语言来描述网络节点之间的关系，用户只需要编辑该文件，GraphViz就会生成相应的网状图。关于GraphViz得更详细介绍及参考手册，请参阅其官方网站：http://www.graphviz.org/
        安装GraphViz后，用户就可以在Doxygen Wizard中的Dot页设置相应的属性。

• 其他

   关于Doxygen使用的文章：
   -学习用Doxygen生成源代码文档 http://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/?S_TACT=105AGX52&S_CMP=tec-csdn