转载

.NET平台开源项目速览(4).NET文档生成工具ADB及使用

很久以前就使用ADB这个工具来生成项目的帮助文档。功能强大,在学习一些开源项目的过程中,官方没有提供CHM帮助文档,所以为了快速的了解项目结构和注释。就生成文档来自己看,非常好用。这也是一个学习方法吧。例如本文在:

.NET平台开源项目速览(2)Compare .NET Objects对象比较组件

.NET平台开源项目速览(3)小巧轻量级NoSQL文件数据库LiteDB

上述2篇文章中最后的资源中就手动制作了CHM帮助文档。有时候我们还可以对源码进行翻译,再制作,效果还不错。今天介绍的ADB工具,我使用的是基于X组件的一个改进版。改进的细节我也不太清楚,反正非常好用。下面来看看介绍和使用方法。

.NET开源目录: http://www.cnblogs.com/asxinyu/p/4329755.html

本文原文地址: .NET平台开源项目速览(4).NET文档生成工具ADB及使用

1.ADB介绍

程序的注释在程序的编写和维护中扮演着相当重要的角色,在Visual C#中,可以为代码创建文档,方法是在XML标记所指的代码块前面,直接在源代码的特殊注释字段中包括XML 标记。编译器编译时将在源代码中搜索所有的 XML 标记,并创建一个XML文档文件。.NET文档生成工具( 下文简称为ADB )通过反射程序集及其代码中的XML注释来创建MSDN形式的API文档。

ADB文档生成工具是博客园 

卢春城

开发的一个开源工具,项目的介绍网址为:

http://www.cnblogs.com/lucc/archive/2008/09/01/1281085.html

注意:使用该软件需先安装 Microsoft HTML Help Workshop, 主要作用有:    

(1)根据程序集及其对应的XML文档文件生成风格类似MSDN的文档,并打包为CHM文件;

(2)将多个程序集对应的文档合并到一个文档中;

(3)自动搜索程序集及其引用的程序集对应的XML文档(包括.Net自带的程序集,如:System.xml);

(4)灵活控制在文档中显示哪些成员(如:只生成公共方法);

(5)界面友好,操作简便。

(6)用户可以根据自己的需要 扩展XML标志

(7)用户可以根据自己的需要编写自定义的文档生成器。

ADB官方提供的最新版是2.3,可以去上面的链接下载最新版,我这里分享的是@大石头使用X组件重新编译后的版本。

2.ADB生成.NET文档过程

使用过程分为3个步骤:

2.1 .NET项目代码注释

ADB代码生成主要是根据项目的注释来进行生成的。例如C#中注释的标记:

/// <summary>获取指定数组中,满足范围的比例</summary> /// <param name="data">目标数据</param> /// <param name="L">下限</param> /// <param name="H">上限</param> public static double FindPrecent(this IEnumerable<Int32> data, Int32 L, Int32 H) {  var t = (double)data.Where(n => n >= L && n <= H).Count();  return t / (double)data.Count();  }

当然还有更多的标记符号,例如example,code,see等等。如果想做很完善的帮助文档,那这些细节处理得越好,那文档的作用就越强大。

2.2 项目设置与生成

项目编译之前,要确认是否生成xml文件,打开 项目属性->生成->输出 节点,如下图:

.NET平台开源项目速览(4).NET文档生成工具ADB及使用

确认勾选xml文档文件选项。生成的时候就是根据这个xml的注释来进行的。

2.3 ADB使用生成CHM文档

打开ADB软件,我在第3节提供2个版本的下载,如果需要自己编译其他版本,打开ADB软件,如下图:

.NET平台开源项目速览(4).NET文档生成工具ADB及使用

输入标题后,添加你要生成的文档的dll文件,可以添加多个,然后如果你生成了对应的xml文件,会自动加载进来。否则会报错。如下图:

.NET平台开源项目速览(4).NET文档生成工具ADB及使用

还可以只添加你想要的类型以及方法。一般非公共类型可以不加进去。最后点”创建文档”就OK了,它会生成到你xml文件的目录。

注意2个小问题:你的CHM的文件标题要规范一点,什么#号,:号等都不要加上去,否则会报错,有时候很头疼。。。经常会忘记这一个,有时候还不止咋搞,就错误。如下图所示,标题就有问题:

.NET平台开源项目速览(4).NET文档生成工具ADB及使用

好了,不说了,说多了都是泪。下面看看我生成的一些文档:

.NET平台开源项目速览(4).NET文档生成工具ADB及使用

效果不错哦。。。赶紧试试。

3.资源与代码

我这里发的是X组件修改版本的源代码,感谢@卢春城  ,@大石头,我只是打酱油的,把它分享出来而已。

  Microsoft HTML Help Workshop 下载

ADB X组件版本源码:ADB_Src.rar

ADB  .NET 4.0版本:ADB_4.0.rar

ADB  .NET 4.5版本:ADB_4.5.rar

正文到此结束
Loading...