生成类库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标记。

///

        /// 登陆用户

        /// 登陆密码

        /// 用户对象

        [OperationContract]

        User GetUserId(string loginName, string loginPassword);

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

三.3 常见注释标签列表

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

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

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

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

另外有需要云服务器可以了解下创新互联scvps.cn，海内外云服务器15元起步，三天无理由+7*72小时售后在线，公司持有idc许可证，提供“云服务器、裸金属服务器、高防服务器、香港服务器、美国服务器、虚拟主机、免备案服务器”等云主机租用服务以及企业上云的综合解决方案，具有“安全稳定、简单易用、服务可用性高、性价比高”等特点与优势，专为企业上云打造定制，能够满足用户丰富、多元化的应用场景需求。