用doxygen+graphviz自动化生成代码文档（附详细教程）

一、引子

用这两个工具可以自动的遍历代码，并且产生代码文档，我们先来看看效果，然后放出这两个工具的下载地址。

二、工具的下载地址

doxygen：http://www.stack.nl/~dimitri/doxygen/download.html

graphviz：http://www.graphviz.org/

三、使用步骤

首先安装doxygen，然后解压下载好的graphviz。接着打开doxygen，按照我下面的图示进行操作就好了。

最后点run就可以了。

附上doxygen能识别的一些注释，这里仅仅是比较常用的，不是全部。为了说明清楚，我把注释和代码一起贴上。

package com.example.kale.myapplication;

/**
 * Created by Jack Tony on 2015/4/3.
 * @brief 这个类是做什么的
 */
public class TestClass {

  /// 枚举
  enum TYPE
    {
        TYPE_01,/*!< 枚举项01 */
        TYPE_02,///< 枚举项02
    };

    /**
     *
     * <pre><b>copyright: kale</b></pre>
     * <pre><b>email: </b>developer_kale@qq.com</pre>
     * <pre><b>company: </b>http://www.cnblogs.com/tianzhijiexian/</pre>
     * <pre><b>All rights reserved.</b></pre>
     * @see 参考项 http://www.cnblogs.com/tianzhijiexian/
     * @brief 方法的简单说明
     * @author 作者的信息
     * @date 2011/8/24 8:37:56
     * @version 0.1
     * @retval c 描述返回值的类型
     * @note 注解，可以是详细的注解
     * @remarks   备注事项（remaks）
     * @attention 注意事项(attention)
     * @warning 警告信息
     * @param a 参数a的说明
     * @param b 参数b的说明
     * @return 本函数返回执行结果
     *
     * @throws Exception
     */
    public String testFunction(int a, String b)  throws Exception{
        return "hello world";
    }
}

输出的测试结果：

详细的步骤图片下载：http://download.csdn.net/detail/shark0017/8564357

下面的详细说明转自：http://blog.chinaunix.net/uid-23670869-id-2948890.html

Project页面，主要包括项目的基本配置。
             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 是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

Messages页面主要用来设置编译时的输出信息选项。编译时的输出信息，主要可以用来提醒一些输入的错误语法。
             QUIET 如果开启，那么表示关闭编译时的输出信息。
             WARN_FORMAT 表示日志输出的格式，没必要修改。
             WARN_LOGFILE 表示信息是否输出到LOG文件，因为有DoxyWizard的存在，所以这个选项没有必要使用。

HTML页面
             CHM_FILE 表示输出的chm文件路径
             GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。             
             TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。
             这个页面关系到生成chm的问题，不过很多选项很简单，一看便知。

Preprocessor 页面是预处理页面，里面也有一些配置，但是个人感觉使用默认就行了。其他的几个页面，基本上都要依赖于某些其他第三方的模块，尽管有些doxygen自带了，但是其详细说明，还得考读者自行研究。

同时附上常用的doxygen命令列表。注意doxygen的注解命令主要分成doxygen自建命令，HTML命令方式和XML命令方式。所有的命令都是以'\'或者'@'字符开头，这表明如果你的注释中有'\'开头的单词，你必须要修改成'\\'。

由于doxygen命令比较多，另外就是doxygen的帮助文档也是非常完善，所以，这里仅仅列举几个常用的命令，其他命令请自行参考帮助文件。

@addtogroup 添加到一个组。
@brief  概要信息
@deprecated 已废弃函数
@details  详细描述
@note  开始一个段落，用来描述一些注意事项
@par  开始一个段落，段落名称描述由你自己指定
@param  标记一个参数的意义
@code .. @endcode 包含一段代码
@fn  函数说明
@ingroup 加入到一个组
@return  描述返回意义
@retval  描述返回值意义
@include 包含文件

如何像MSDN那样在左边的树中显示函数列表？
       打开[Expert...]的HTML页面，然后选中TOC_EXPAND即可。

参考自：

http://blog.csdn.net/liuxuezong/article/details/6713807
http://www.cnblogs.com/homezzm/archive/2013/07/02/3166602.html
http://wenku.baidu.com/link?url=XtIQOfIvSriE9_MWDqhxsPfxm9OAVpCwcwkLunBVIr7Im9FVKBy9ZB2-ZdjiSpT0obgs8Gh12NXVs02oRJ54Sj3_S_N-UleYoFAAIf29XcG
http://www.xjtudll.cn/Exp/245/

http://blog.chinaunix.net/uid-23670869-id-2948890.html