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;
    }  

3 配置步骤

下面就讲解下如何使用了

运行doxygen的步骤和基本界面如下图，

（1）Destination Directory可以用相对路径，如：运行路径是C:/Users/263/Desktop,那么上面的路径直接填写doc/doc

（2）Graphviz生成函数调用图源文件和工作目录必须是英文。

这种选择，在html中没有搜索。搜索功能在CHM中区产生。

要生成HTML有搜索功能的文档，需要再html选项中选择plain html。

说明：编码格式，UTF-8 是首选。如果需要显示中文则选择GB2312.

TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。

OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果

是纯C代码，建议选择。

SUBGROUPING这个选项选择后，输出将会按类型分组。

Build页面，这个页面是生成帮助信息中比较关键的配置页面：

EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。

EXTRACT_PRIVATE 表示：输出private函数。

EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。

HIDE_UNDOC_MEMBERS 表示：那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。

INTERNAL_DOCS 主要指：是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都

将在目标帮助中不可见。

CASE_SENSE_NAMES 表示：是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种

字母相关的语言来说，建议永远不要开启。

HIDE_SCOPE_NAMES 表示：域隐藏，建议永远不要开启。

SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列

表。

INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。

SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显

示。

GENERATE_TODOLIST ：是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显

示在一个页面中，其他的GENERATE选项同。

SHOW_USED_FILES ：是否在函数或类等的帮助中，最下面显示函数或类的来源文件。

SHOW_FILES ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

说明：1，CHM_FILE文件名需要加上后缀（xx.chm）。

2，如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项，此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe，如：C:\Program Files\HTML Help Workshop。

3，为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。

4，GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。

5，TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。

 参考

http://blog.csdn.net/fly542/article/details/7164633