生成类库chm帮助文档

 

生成类库chm帮助文档

     

目 录

第一章配置说明3

1.1本地服务器信息3

 

第一章 
生成文档说明

一.1 生成帮助文档的作用

项目开发与各部门配合时,给他们提供一个外部服务,既然是提供给别人（研发、测试等）使用的,当然需要告诉别人怎么来用你的服务,这也就是我们常说的技术文档。各组之间传递技术文档的方式有很多种。这里我知道的大概有以下几种：

    第一：口头传递技术文档，也就是没有实质的文档资料，口头说明一下即可，这种情况局限于沟通起来非常方便的开发团队中，例如就坐在一个办公间等等。

    第二：以文本形式，把如何使用的技术点记录下来，这个方法有什么用，那个属性是做什么的等等，这种方式无疑是表述最清楚的，单独的文档中你甚至可以用图的方式教导使用者，但缺点就是维护起来相当麻烦，而且费时。如果哪天服务的实现有了比较大的改变，那更新这个文档就非常麻烦了。

    第三：利用工具，配合.net的注释来自动生成帮忙文件，这里就是本文所提到的Sandcastle Help File Builder了，后面简称为SHFB。它是Sandcastle的一个可视化工具，用户不用记住大量命令来完成文档的编译。它最终可以生成例如chm文件，内容风格可选MSDN，让使用都可以感到非常亲切。

一.2 Sandcastle 概述

为了满足这部分文档编写的需要，Microsoft 推出了一种用于快速生成 .NET 类库文档的工具，代号为 Sandcastle，该工具用来通过代码中的 XML 文档注释快速生成类似 MSDN 样式的帮助文档。它的文档输出格式支持 Help 1.x (*.chm)，Help 2.0 (HxS) 和网站 (ASP.NET 和 HTML)，您在编写文档上仅仅需要做的工作，就是努力的写好所有 XML 文档注释，并最终利用 Sandcastle 进行批量生成。

Sandcastle 被 Microsoft 内部用来直接生成 .NET Framework 核心类库参考文档，它是 MSDN 和 .NET Framework SDK 的一部分。

目前，Sandcastle 没有图形界面，但它提供了强大的功能，包括支持 prototype 样式、Visual Studio 2005 样式和 Visual Studio 2008 新的文档设计样式；它能对代码示例进行语法高亮，自动生成多种语言的过滤、语法、生成索引、内容目录、搜索；除此之外，它提供的命令行工具和批处理文件能够帮助我们生成自定义的帮助文档的本地化版本。

Sandcastle 提供的主要命令行工具有两个：BuildAssembler.exe 和 XslTransform.exe。BuildAssembler 用来对帮助文档源 (*.dll, *.exe, *.xml) 进行反射，找到所有的可用于生成文档的程序集、命名空间和类型，以及它们附加的 XML 文档注释，生成待转换的 XML 文件；XslTransform 用来对 BuildAssembler 生成的 XML 文件转换成特定的输出格式，如 Visual Studio 2005 样式的 chm 文件

注：Sandcastle 支持将多个程序集的XML文档注释生成一个chm文件的功能，可以将多个程序集和对应XML文档注释分别放在两个文件夹下，然后用AddFolder功能 一次性将文件夹下的文件添加到项目中，这样就可以将多个程序集的XML注释合并生成一个CHM文档了。

 

 

一.3 生成文档有以下特点

        类似于MSDN布局的界面。

        自动生成索引项、内容项目表、主题块和页面布局，提高一致性和熟悉程度。

        自动生成语法宣称部分。

        自动生成继承表。

        代码彩色化。

        提供多种风格和语言选择，终端用户可从中选择自己最喜欢的形式。

        输出结果以HTML和CSS形式显示，微软承诺将来提供更多选择。

 

一.4 利用图形化工具 Sandcastle Help File Builder

使用这个工具，您可以用图形化的界面批量生成多个程序集的文档，还能生成基于 ASP.NET 和 HTML 的网站。它只需要您简单的作出几个设置，就能非常方便的帮助您生成专业的，带有高级语法过滤、语法高亮、搜索和导航功能全功能站点。

 

 

总结：Sandcastle Help File Builder能够非常好的和VS合作，制作出MSDN风格的帮忙文档，即有效的对项目保存了技术文档又降低了沟通成本。

 

 

 

 

 

 

 

 

 

 

 

 

 

第二章 Sandcastle Help File Builder说明

二.1 SHFB的软件环境

下载地址：

 

下载后解压缩到目录：

 

二.2 SHFB安装过程

二.3 安装步骤

 

 

按步骤进行安装

 

二.4 配置项目中生成xml文档

 

 

 

二.5 创建SHFB文档项目

 

“File”菜单——“New Project”

右击项面前目今的”Documentation Sources”——“Add Documentation Source…”，添加要生成文档的.dll和.xml文件。

设置项目标属性，如HelpTitle，HtmlHelpName等。

生成项目，“Documentation”菜单——“Buid Project”

 

a.打开软件后首先新建解决方案，注意不要建在桌面等位置，否则生成时会报错。

b.解决方案建成后，在Project Explorer 中右击 Documentation Sources 上右击添加需要生成帮助文档的dll文件。图中①处为我添加的需要生成帮助文档的dll文件

c.底下Content Layout1.content为生成的帮助文档的样式，完全可以不要。

d.选择要生成帮助文档的格式，如图中②处，我要生成html格式的帮助文档，也可以选择chm文档

 

第三章 注释文档规范

三.1 注释的必要性

.Net允许开发人员在源代码中插入XML注释，这在多人协作开发的时候显得特别有用。 C#解析器可以把代码文件中的这些XML标记提取出来，并作进一步的处理为外部文档。 这篇文章将展示如何使用这些XML注释。 在项目开发中，很多人并不乐意写繁杂的文档。但是，开发组长希望代码注释尽可能详细；项目规划人员希望代码设计文档尽可能详尽；测试、检查人员希望功能说明书尽可能详细等等。如果这些文档都被要求写的话，保持它们同步比进行一个战役还痛苦。

为何不把这些信息保存在一个地方呢？？最明显想到的地方就是代码的注释中；但是你很难通览程序，并且有些需要这些文档的人并不懂编码。最好的办法是通过使用XML注释来解决这些问题。代码注释、用户手册、开发人员手册、测试计划等很多文档可以很方便的从XML注释中获得。本文讲解.Net中经常使用的XML注释.主要使用C#语言.Net平台支持的其他语言使用的XML注释格式基本相同.并且在本系列文章的下一讲中讲解如何使用工具将XML注释内容转化为帮助文档.

三.2 代码注释规范

代码注释规范需要使用以三个斜杠 (///) 开始注释，这些注释后面必须紧跟它们所注释的用户定义类型（如类、委托或接口）或者成员（如字段、事件、属性或方法）.对注释解说需要使用有效的xml标记。

        

///

        /// 用户登录

        ///

        /// loginName">登陆用户

        /// loginPassword">登陆密码

        /// 用户对象

        [OperationContract]

        User GetUserId(string loginName, string loginPassword);

这里嵌入的summary,param,returns标记仅仅是Visual Studio能够识别的一部分标记，然而在智能感知IntelliSense中，并没有把c#规范中所有的标记列出来，遗失的部分只能用手工插入。 这些手工标记是非常有用的，如果恰当地设置他们，对导出成外部说明文件将非常有帮助。

三.3 常见注释标签列表

注释的使用很简单,但是我们使用到的注释很少.这是因为大部分项目中注释的作用仅仅是给程序员自己看.如果想要生成类似MSDN这样的文档,我们需要了解更多的注释标签.下面是我整理的常用的注释标签:

标签名称	说明	语法	参数
	标记应当用于描述类型或类型成员。使用 添加针对某个类型说明的补充信息。  标记的文本是唯一有关 IntelliSense 中的类型的信息源，它也显示在 对象浏览器 中。	Description	description:对象的摘要。
	标记应当用于方法声明的注释中，以描述方法的一个参数。 有关  标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。	name='name'> description	name:方法参数名。将此名称用双引号括起来 (" ")。 description:参数说明。
	标记应当用于方法声明的注释，以描述返回值。	Description	description:返回值的说明。
	使用  标记添加有关类型的信息，以此补充用  指定的信息。此信息显示在对象浏览器中。	Description	description:成员的说明。
	标记使您可以指定哪些异常可被引发。此标记可用在方法、属性、事件和索引器的定义中。	cref="member"> Description	cref: 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将member 转换为输出XML 中的规范化元素名。必须将 member括在双引号 (" ")中。 有关如何创建对泛型类型的 cref 引用的更多信息，请参见 description:异常的说明。
	标记使您得以描述属性所代表的值。请注意，当在Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加  标记。然后，应该手动添加  标记以描述该属性所表示的值。	<value> property-description value>	property-description:属性的说明
	使用  标记可以指定使用方法或其他库成员的示例。这通常涉及使用 标记。	<example> Description example>	description: 代码示例的说明。
	标记为您提供了一种将说明中的文本标记为代码的方法。使用  将多行指示为代码。	Text	text :希望将其指示为代码的文本。
	使用  标记将多行指示为代码。使用指示应将说明中的文本标记为代码。	<code> Content code>	content:希望将其标记为代码的文本。
	标记使您得以从文本内指定链接。使用  指示文本应该放在“另请参见”节中。	<see cref="member"/>	cref: 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查给定的代码元素是否存在，并将member 传递给输出XML 中的元素名称。应将 member 放在双引号 (" ") 中。
	标记用于诸如 ， 或 等标记内，使您得以将结构添加到文本中。	<para>contentpara>	content:段落文本。
*	提供了一种插入代码的方法。	<code src="src"language="lan"encoding="c"/>	src:代码文件的位置 language:代码的计算机语言 encoding:文件的编码
*	用以在文档中插入图片	<img src="src"/>	src:图片的位置，相对于注释所在的XML文件
*	用以在文档中插入文件，在页面中表现为下载链接	<file src="src"/>	src:文件的位置，相对于注释所在的XML文件
*	提供一种注释本地化的方法，名称与当前线程语言不同的子节点将被忽略	<localize> <zh-CHS>中文zh-CHS> <en>Englishen> ... localize>

 

三.4 

 

 

三.5 类注释

 

 

三.6 方法注释

 

 

 

需要注意的几点:

 

1) 最开始seealso标签添加在了remarks标签中,所以在See Also区域没有添加上方法的连接. 解决方法是把seealso标签放在summary标签中.

2) 异常类的cref属性需要设置成编译器可以识别的类, 这样才可以在帮助文档中点击.比如上面的System.ApplicationException异常点击后进入微软的在线MSDN查询.如果是自己定义的异常, 需要此异常类也在你的帮助文件中.一般提供注释XML和依赖DLL即可.

 

三.7 属性注释

属性的注释也很简单.和类不同的地方在于属性要使用标签而不是进行描述

 

 

 

 

 

第四章 参考资料

1、 使用SandCastle创建.Net帮助文档

http://www.cnblogs.com/DotNetNuke/archive/2009/04/23/1441899.html

2、 Sandcastle Help File Builder源码

http://shfb.codeplex.com/releases/view/121365

3、 Sandcastle源码

http://sandcastle.codeplex.com/SourceControl/latest

http://sandcastle.codeplex.com/releases/view/47665

4、 使用.NET中的XML注释

http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/1380416.html

 

文章中的部份图片来源网络的图片，版权归相关图片的所有者。 

 如果图片有对您造成影响，可联系我处理。