用 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 ---------------------------------
# 文件的注释格式
# 注释文件,格式: ///@file 文件名 文件的简短注释.
///@file socket_c.h  head file of class socket_c.
# 文件的详细注释.
///Define the interface of class socket_c.
# 普通注释,不会生成在文档中.
//$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $

# 类的注释,格式: ///@brief 简短注释内容.
///@brief class of server socket.
class socket_c
{
private:

public:
    # 函数的注释格式
    # 函数的注释,格式: ///@brief 函数的简短注释.
    ///@brief handle the connections of clients.
    # 参数注释,格式: ///@param 参数的简短注释.
    ///@param server the server ip address.
    ///@param serv_port the server #port.
    # 返回值注释,格式: ///@return 返回值的简短注释.
    ///@return connected socketfd.
    # 具体返回值的注释,格式: ///@retval 返回值 该返回值的注释.
    ///@retval connfd on success.
    ///@retval 0 on EINTR - system call.
    ///@retval -1 on error.
    # 参见...,格式: ///@see 参见的类/文件等.
    ///@see main_ppc.cpp
    int accept_client(const int listenfd);
};

# 自定义类型的注释
///@brief structure of child process.
struct child_proc_s
{
    # 行尾的注释,格式: ///< 注释内容.
    pid_t child_pid;    ///<child process id.
    int child_pipefd;    ///<parent's stream pipe to/from child.
};

# 全局变量的注释,也可以采用上面的行尾格式进行注释.
///gloable variable for signal.
pid_t g_pid = 0;
----------------------------- Example End ---------------------------------

3 配置文件的生成与修改

    Doxygen的功能强大,配置选项也十分多. 如果是命令行模式, 有些不便. 因此建议使用GUI的Doxywizard(可以从<开始>菜单中运行). 下面就对我个人认为比较重要的选项,并结合实例 (生成html文档) 进行简单说明.
    下面列出的一般是需要修改的,未列出的我采用缺省值.

# Project选项
#---------------------------------------------------------------------------
# Staff_TPC是生成文档的项目名,会显示在文档中.
PROJECT_NAME           = Staff_TPC
PROJECT_NUMBER         = 1.0    # 项目版本号
# 生成文档的输出路径
OUTPUT_DIRECTORY       = "f:/My Documents/cpp/horin/staff/"
# 生成文档的语言,缺省是English,也可以是简体中文等.
OUTPUT_LANGUAGE        = English
JAVADOC_AUTOBRIEF      = YES    # 打开此选项.

# Build 选项
#---------------------------------------------------------------------------
SHOW_INCLUDE_FILES     = NO        # 不显示所有包括的文件.

# input 选项
#---------------------------------------------------------------------------
# 要生成文档的源文件的路径. 如果是一个目录,则是该目录下的所有文件; 当然,也可以
# 是具体的某个文件.
INPUT                  = "f:/My Documents/cpp/horin/staff/tpc/"
# 输入文件的匹配模式,下面是c / c++语言的设置.
FILE_PATTERNS          = *.c /
                         *.cpp /
                         *.h /
                         *.hpp
RECURSIVE              = YES    # 需要递归处理子目录.

# source browser选项
#---------------------------------------------------------------------------
# 如为SOURCE_BROWSER和INLINE_SOURCES都设置为YES, 则生成的文档中会包括源代码
# (即.cpp文件),这可以方便阅读时查看源代码.
SOURCE_BROWSER         = NO
INLINE_SOURCES         = NO
STRIP_CODE_COMMENTS    = YES    # 忽略普通的文档注释.
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
VERBATIM_HEADERS       = YES

# HTML 选项
#---------------------------------------------------------------------------
GENERATE_HTML          = YES    # 需要生成html格式的文档.
GENERATE_HTMLHELP      = YES    # 需要生成windows HTMLHELP格式的目录,以方便阅读.
GENERATE_TREEVIEW      = YES    # 需要生成树视图,以方便阅读.

# LaTeX 选项
#---------------------------------------------------------------------------
GENERATE_LATEX         = NO        # 不需要生成LaTeX输出.

# dot 选项  # 此选项是生成图形,建议(需要)安装graphviz.
#---------------------------------------------------------------------------
CLASS_DIAGRAMS         = YES
HIDE_UNDOC_RELATIONS   = YES
HAVE_DOT               = YES    # 已经安装graphviz.打开此选项.
CLASS_GRAPH            = YES    # 生成类图
COLLABORATION_GRAPH    = YES    # 生成协作图
UML_LOOK               = NO

    在上面根据自己的需要对各个选项进行了配置,下面很重要的一步,就是把配置保存下来. 呵呵,这是大家最擅长的了. 可以命名配置文件为Doxygen-YourName.txt, 今后只需修改project和input选项,即可重用.

4 文档的生成

    在Doxywizard中打开上面的配置文件Doxygen-YourName.txt, 根据需要修改project和input选项(也可以在文本编辑器中直接修改Doxygen-YourName.txt), 点击菜单Doxygen->Run(ctrl+r),稍微休息一会,你就可以看到在OUTPUT_DIRECTORY路径下生成了一个html的子目录.该子目录下就是你需要的文档. 运行index.html文件, 是否见到了你想要的.很有可能,还见到了你意想不到的.

5 Doxygen的其他用途

    Doxygen配合graphviz, 可以生成UML设计图形,如类图,协作图. 如你拿到一份源代码,因为类的关系复杂,或者没有文档, 此时你就可以利用Doxygen来进行简单的反向工程了.

6 Doxygen与Python

6.1 Doxygen 1.4.4 之前的版本

    要用Doxygen来自动为Python脚本文件产生文档，早期版本(1.4.4 之前)需要一个第三方的filter：
          http://i31www.ira.uka.de/~baas/pydoxy/
    下载该filter后(pythfilter.py，一个Python脚本文件)：
 - 把该文件拷贝在Doxygen的安装目录下;
 - 运行doxywizard, 并打开自己默认的配置文件, 打开 Input 选项卡:
   - 在FILE_PATTERNS中添加: *.py
   - 在INPUT_FILTER中输入: D:/Python24/python pythfilter.py -f
     其中, python.exe的路径, 需要根据具体情况修改.
   - 选中FILTER_SOURCE_FILES选项.
   - 保存该配置文件, 以备后用.

    在Python中注释格式:
    The filter translates classes and funtions into empty C++ stubs and transforms all comments starting with ## and all doc strings into doxygen comment blocks.
Inside those comments you can use any doxygen markup as you would do in your C/C++ code as well.
    Furthermore, it puts the entire contents of a file into a namespace with the name of the file (without the .py suffix).

    上述英文简单翻译如下：
 - 把整个.py文件作为一个namespace(与文件名同名);
 - 转换以"##"开始的注释;
 - 转换所有的 Doc 字符串;
 - 在注释中可以使用任何Doxygen支持的标注.

    简单示例:

## /file example.py
## /brief An example Python program.

    ## protected:

    def spam(amount):
        """Return an amount of spam.

        /param amount (/c int) The amount of spam.
        /return An amount of spam.
        """

        return amount*"spam"

6.2 Doxygen 1.4.4 及之后的版本

    Doxygen 从 1.4.4 版本开始支持 Python 代码的解析. 注释书写格式可以是 Python doc 的标准注释方式, 也可以是 pythfilter.py 风格的注释. 下面各举一例.

6.2.1 采用Python doc的标准注释方式，但该方式不支持 doxygen 的特殊指令。

"""Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

class PyClass:
    """Documentation for a class.

    More details.
    """

    def __init__(self):
        """The constructor."""
        self._memVar = 0;

    def PyMethod(self):
        """Documentation for a method."""
        pass

6.2.2 采用 pythfilter.py 风格的注释，即以 '##' 开始，此风格支持特殊指令。

## Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

## Documentation for a class.
#
#  More details.
class PyClass:

    ## The constructor.
    def __init__(self):
        self._memVar = 0;

    ## Documentation for a method.
    #  @param self The object pointer.
    def PyMethod(self):
        pass

    ## A class variable.
    classVar = 0;

    ## @var _memVar
    #  a member variable