使用Doxygen生成C#帮助文档

一． 什么是Doxygen?

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。
Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。
因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。

二． 准备软件

2.1 doxygen

官网：http://www.doxygen.nl/

下载地址：http://www.stack.nl/~dimitri/doxygen/download.html

2.2 graphviz

官网：http://www.graphviz.org/content/dot-dotexe

注：这个软件不是必需的，如果需要使用更强大的功能比如类继承体系图等则需要安装此软件配置使用，需要安装Java环境
下载地址：http://www.graphviz.org/Download_windows.php

 

2.3 Microsoft HTML Help Workshop

chm文件制作工具

三个软件

三． C#注释

<Summary> 对整体进行概要性描述

<summary>Description</summary>

类、属性（不推荐）、方法等 

<para> 跟在Summary之后，对方法所涉及的入口参数进行有效的解释

<param name=username>本参数是用户的帐号</param>

方法的入口参数; 

<returns> 对方法的返回值进行解释;

<returns>返回值零代表操作成功，-1代表操作不成功</returns>

方法的返回值; 

<remarks> 对一些语句进行备注性描述

<remarks>本类需要调用另外一个User类相关方法</remarks>

类、方法、属性等; 

<see> 在生成的文档中产生一个连接到其它描述的超链接;

<see cref=”[member]”/>

可以在其它注释标识符中加入 

<seealso> 与上者的区别是本标识符显示超链接在一个文档的尾部的“See Also”区域，而前者在文档之中;

<seealso cref=”[member]”/>

不可以在其它注释标识符中加入 

<value> 对一个属性进行概要性解释;

<value>这是一个public属性</value>

属性 

<code> 如果需要置入一部分源代码段，可以使用本标识符将其标记出来

<code>

public int add(int a,b)

{

return a+b;

}

</code>

可以在其它注释标识符中加入 

<exception> 对程序中可能抛出的异常做解释;

<exception cref=”System.Exception”>抛出的异常情况</exception>

在方法当中如果有抛出异常，如“try…catch结构”时可以使用本标识符做解释 

<permission> 对方法的访问权限做一些解释：

<permission cref=”System.Security.PermissionSet”>这是公共方法</permission>

方法，属性 

<c> 与<code>标识符基本相同，但本标识符仅用于单行代码;

<c>return a+b;</c>

可以在其它标识符中插入使用; 

<example> 举例说明，通常与<code>配套使用;

<example> 以下示例说明如何调用Add方法:

<code>

class MyClass

{

public static int Main()

{

return Add(1+2);

}

}

</code>

</example>

可以在其它标识符中插入; 

<paramref> 在其它地方引用一个入口参数

<paramref cref=”a”>请注意，这是一个整型参数</paramref> 

四． 配置

4.1 Doxygen工作目录

请选择一个已存在的非中文路径的文件夹，如下图：

4.2 Wizard 向导

      4.2.1 Project 项目

      4.2.2 Mode 模式

 

      4.2.3 Output 输出

将With search function的钩去掉

plain HTML,为下图一，with navigation panel为下图二

  

      4.2.4 Diagrams 图表

(Use built-in class diagram generator)将使用内置的生成功能生成每个类的类图，只有一个类是不为生成的。

如果需要更加大的功能比如类继承体系图请选择第三项(Use dot tool from the GraphViz package)需要安GraphViz。

4.3 Export 导出

      4.3.1 Project  项目

OUTPUT_LANGUAGE选择chinese TAB_SIZE是Tab的长度

      4.3.2 Build 构建

默认是会生成public方法，这里也选择EXTRACT_ALL。它保证输出所有public方法及project方法，EXTRACT_STATIC是生成静态方法。

 

      4.3.3 Input 输入

Input为输入目录，支持多个目录，我们可以放入项目目录和include目录，下面的Exclude是忽略目录与文件，可自行添加。

      4.3.4 Index 索引

选择ALPHABETICAL_INDEX，类中将有一个组合类型索引项。

生成的索引如下图所示

      4.3.5 HTML

如果你之前选择了(prepare form compressed HTML(.chm))这里抽GENERATE_HTMLHELP项会是选择状态，它下面的CHM_FILE填写你的CHM文档的名字（要加上.chm）。HHC_LOCATION则选择你的HTML Help WorkShop安装目录下的HHC程序，一般会在C:/Program Files (x86)/HTML Help Workshop/hhc.exe。选择TOC_EXPAND会生成左边的树目录。

      4.3.6 Dot

如果你选用内置的生成功能（Use build-in class diagram generator）此时CLASS_DIAGRAMS会是选择状态，而HAV_DOT是未选择状态，如果你选择用GraphViz的dot工具生成（Use dot tool from the GraphViz package）情况则相反，请你选择上CLASS_DIAGRAMS。此时你需要设置下面的DOT_PATH为GraphViz的安装目录，否则将无法生成。

另外以下选项选择则生成对应的图，不选择则不生成。

CLASS_GRAPHS                   类图

COLLABORATION_GRAPH      协作图

GROUP_GRAPHS                   组图

UML_LOOK                           是否UML外观

INCLUDE_GRAPH                   include

INCLUDED BY GRAPH             被include

CALL_GRAPH                        调用

CALLER_GRAPH                    被调用

DIRECTORY_GRAPH               目录图

GRAPHICAL_HIERARCHY        继承体系图

五.Run 运行

配置好后中进入Run选项卡单击 Run Doxygen 即开始生成，等待生成完毕后点击 “Show HTML output”

六.HTML效果图

 

 

七.CHM效果图

分享一下我的Doxygen配置文件：http://pan.baidu.com/s/1hqh5Clm

八.提醒

提醒一下，如果是WIN8的操作系统，建议设置dot的兼容性，并以管理员身份运行，否则一直会弹出dot停止运行的警告框