使用Doxygen生成net帮助文档

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

二．下载地址
doxygen-1.8.4-setup.exe
http://jaist.dl.sourceforge.net/project/doxygen/rel-1.8.4/doxygen-1.8.4-setup.exe
graphviz-2.30.1.msi(不是必需)如果需要使用更强大的功能比如类继承体系图等则需要安装此软件配置使用
http://www.graphviz.org/pub/graphviz/stable/windows/graphviz-2.30.1.msi

三． 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>

四．配置
Step 1:是Doxygen的工作目录，请指定一个已存在的非中文的文件夹
主界面如下图：

使用Doxygen生成net帮助文档

Step 2:具体配置

Wizard选项卡

Project

使用Doxygen生成net帮助文档

Mode

使用Doxygen生成net帮助文档

Output

将With search function的钩去掉

使用Doxygen生成net帮助文档

Diagrams

使用Doxygen生成net帮助文档

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

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

Export选项卡

Project

OUTPUT_LANGUAGE选择chinese

TAB_SIZE是Tab的长度

使用Doxygen生成net帮助文档

Build

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

使用Doxygen生成net帮助文档

Input

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

使用Doxygen生成net帮助文档

Index

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

使用Doxygen生成net帮助文档

生成的索引

使用Doxygen生成net帮助文档

HTML

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

使用Doxygen生成net帮助文档

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 继承体系图

使用Doxygen生成net帮助文档

配置好后中进入Run选项卡单击Run Doxygen即开始生成。

生成完毕后

使用Doxygen生成net帮助文档

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

namespace DoxygenTest

{

    public class Test

    {

        /// <summary>

        /// 这个是为了测试生成的文档

        /// </summary>

        /// <example>

        ///     <code>

        ///         Test.DoxygenTest("测试",1000);

        ///     </code>

        /// </example>

        /// <param name="str">参数1是字符串</param>

        /// <param name="int1">这个是整型</param>

        /// <returns>返回空串</returns>

        public static string DoxygenTest(string str, int int1)

        {

            return string.Empty;

        }

    }

}

程序代码

配置文件下载地址

秒客网

使用Doxygen生成net帮助文档

相关文章