Doxgen+Graphiz+htmlhelp配置

查看一些开源码常常被一些函数的调用关系给绕进去。找个工具生成个调用关系图或简单的文档对于帮助阅读程序有非常大的帮助。

1 doxgen+graphviz+htmlhelp简单介绍

1.1 doxgen+graphviz+htmlhelp简单介绍

doxygen生成美丽的调用关系图，那就必须安装下图形生成工具graphviz软件，要通过html生成chm文档，那就要用htmlhelp软件了。doxygen生成html文档或其它格式的文档软件。

首先下载三个软件，均下载windows下的安装包，

doxygen、Graphviz 、htmlhelp地址例如以下：

http://download.csdn.net/detail/fasfewatgerjhytsjy/8149961

1.2 眼下Doxgen可处理的语言

眼下Doxygen可处理的程序语言包括：

C/C++

Java

IDL (Corba, Microsoft及KDE-DCOP类型)

而可产生出来的文档格式有：

HTML

XML

LaTeX

RTF

Unix Man Page

而当中还可衍生出不少其他格式。

HTML能够打包成CHM格式，而LaTeX能够透过一些工具产生出PS或是PDF文档。

2 关于文档凝视的要求

2.1 文档凝视的类型

并不是全部的批注都会被Doxgen所处理。必须按照正确的格式撰写批注。

原则上。Doxgen仅处理与程序结构相关的批注。如Function，Class，档案的批注等。

对于Function内部的批注则不做处理。Doxgen可处理以下几种类型的批注。

（1）JavaDoc类型：

/**
* ... 批注 ...
*/

（2）Qt类型：

/*!
* ... 批注 ...
*/

（3）单行型式的批注：

/// ... 批注 ...

或

//! ... 批注 ...

我的推荐：多行用JavaDoc，单行用/// ... 批注 ...

2.2 文档凝视的位置

Doxgen对于批注视为在解释后面的程序代码。也就是说，不论什么一个批注都是在说明其后的程序代码。

对于批注前面的程序码，Doxgen仅仅能识别class的member或者Function的參数上。须要以下格式的批注符号。

/*!< ... 批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...

2.3 凝视指令和格式

使用Doxgen产生说明文档时候，Doxgen会帮助您parsing您的程式码。而且根据程序结构建立相应的文件。然后将您的批注根据其位置套入正确的地方。除了文字以外，另一些其他特别的指定，如@param。@return等。通过这些指令能够告诉Doxgen后面的批注是在说明什么东西。Doxgen通过指定，能帮助我们做些特别的处理或者排版，甚至是制作參考连结。

（1）经常使用指令

@file	档案的批注说明。
@author	作者的信息
@brief	用于class 或function的批注中，后面为class 或function的简易说明。
@param	格式为 @param arg_name 參数说明主要用于函式说明中，后面接參数的名字。然后再接关于该參数的说明。
@return	后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。
@retval	格式为 @retval value 传回值说明主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。

Doxygen 所支持的指令非常多，有些甚至是关于输出排版的控制。

您可从Doxygen的使用说明中找到详尽的说明。

（2）我们先说明在Doxygen 中对于类别或是函数批注的一个特定格
式。
    /**
     * class或function的简易说明...
     *
     * class或function的具体说明...
     * ...
     */

在Doxygen 处理一个class 或是function注
解时，会先推断第一行为简易说明。这个简易说明将一直到空一行的
出现。

或是遇到第一个"." 为止。之后的批注将会被视为具体说明。

两者的差异在于Doxygen 在某些地方仅仅会显示简易说明。而不显示详
细说明。如：class 或function的列表。
还有一种比較清楚的方式是：

指定@brief的指令。

这将会明白的告诉
Doxygen。何者是简易说明。比如：

    /**
     * @brief class或function的简易说明...
     *
     * class或function的具体说明...
     * ...
     */
（3）除了这个class及Function外，Doxgen也可针对文件做说明，条件是该批注须要置于文件的前面。主要也是利用一些指令。通常这部分注解都会放在档案的開始地方。如：

/*! @file myfile.h
        @brief 文件简易说明

        具体说明.

        @author 作者信息
    */

（4）举例

以下我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式：
example.h:
/**
* @file 本范例的include档案。

*
* 这个档案仅仅定义example这个class。

     *
     * @author garylee@localhost
     */
    #define EXAMPLE_OK  0   ///< 定义EXAMPLE_OK的宏为0。

    /**
     * @brief Example class的简易说明
     *
     * 本范例说明Example class。

     * 这是一个极为简单的范例。
     *
     */
    class Example {
        private:
            int var1 ; ///< 这是一个private的变数
        public:
            int var2 ; ///< 这是一个public的变数成员。
            int var3 ; ///< 这是还有一个public的变数成员。
            void ExFunc1(void);
            int ExFunc2(int a, char b);
            char *ExFunc3(char *c) ;
    };


example.cpp:
    /**
     * @file 本范例的程序代码档案。

     *
     * 这个档案用来定义example这个class的
     * member function。
     *
     * @author garylee@localhost
     */

    /**
     * @brief ExFunc1的简易说明
     *
     * ExFunc1没有不论什么參数及传回值。
     */
    void Example::ExFunc1(void)
    {
        // empty funcion.
    }

    /**
     * @brief ExFunc2的简易说明
     *
     * ExFunc3()传回两个參数相加的值。
     *
     * @param a 用来相加的參数。

* @param b 用来相加的參数。
* @return 传回两个參数相加的结果。

     */
    int ExFunc2(int a, char b)
    {
        return (a+b);
    }

    /**
     * @brief ExFunc3的简易说明
     *
     * ExFunc3()仅仅传回參数输入的指标。
     *
     * @param c 传进的字符指针。
     * @retval NULL 空字符串。
     * @retval !NULL 非空字符串。
     */
    char * ExFunc2(char * c)
    {
        return c;
    }