用 Doxygen 自动生成文档

              用 Doxygen 自动生成文档

             Horin|贺勤
        Email: horin153@msn.com
        Blog: http://blog.csdn.net/horin153/

    本文只是 Doxygen 简单的介绍,必然有许多错误和不足,望大家指正!

    大家在平时的编程过程中,都会在代码中插入一些注释,对文件,类,函数,全局变量等进行简单说明.项目完成后,一般也要编写项目的文档,如何利用源代码及其中的注释,自动生成图文并茂的文档,就是下面要介绍的.
    本文仅以作者常用的 c++ & Python 语言为例说明。


1 工具

    文档自动生成的工具软件,除了商业化的如Rational SoDA等,更有开源的Doc++和Doxygen等. 本文主要介绍功能全面的Doxygen.
    Doxygen可以对C++, C, Java, Python等语言进行解析并生成HTML,LaTeX,RTF,man page,XML等格式的文档.

    除了必备的Doxygen (http://www.stack.nl/~dimitri/doxygen/), 如果你还想生成漂亮的类图等,还需要下载graphviz (Doxygen 采用的绘图工具,http://www.graphviz.org/Download..php).


2 Doxygen 的注释格式

    Doxygen 的注释格式十分灵活.可以是JavaDoc, Qt和仿c++风格, 并且可以混合使用. 如果你熟悉Doc++,就按照你以前的风格写好了:). 下面对每种风格简单举例:

 -- JavaDoc风格:
/**
 * your comment text.
 */
 -- Qt风格:
/*!
 * your comment text.
 */
 -- 仿c++风格:
///                               //!
/// your comment text.      或者: //! your comment text.
///                               //!

    因为我一直喜欢用c++的单行注释风格(即'//'),所以下面举例就以仿c++风格为例. 下面注释中的'@'和'/'等价,可以根据爱好选用.
    因为是在头文件中定义接口,所以注释也就主要集中于头文件中. 如果你想在实现文件中注释,其效果和在头文件中是一样的.下面就举一个实例.

备注:a) '#' 后面的注释是我加的简单解释.不属于文档注释内容.
     b) Doxygen 允许一条简短注释,加上一条详细注释.其格式也是多样的. 一般,在 JAVADOC_AUTOBRIEF = NO时,简短注释(///@brief )后空一行,然后再是详细注释. 当 JAVADOC_AUTOBRIEF = YES时,并且简短注释以第一个句号结束,句号后跟一空格(即'. ');或者是新起一行,就可以写详细注释了.示例如下:

# 简短注释. 详细注释.
/// Brief description which ends at this dot. Details follow
/// here.

    c) 如果同一代码条目在声明和定义处都有简短注释和详细注释, 则文档只采用声明前的简短注释和定义前的详细注释.
    d) 如果是在行尾注释变量,参数等,在你选用的注释格式后面加上'<', 如: ///<行尾的注释.


----------------------------- Example Begin --------