使用.NET中的XML注释 -- XML注释标签讲解

将注释生成XML文件

常见注释标签列表

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

生成注释文档

一、安装软件：

从以下网址中下载并安装,SandCastleg下载地址:
http://sandcastle.codeplex.com/releases/view/47665

从以下网址中下载并安装,HTML Help Workshop下载地址:
http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=21138

二、文件准备：

准备dll文件和注释的xml文件.比如本文实例的两个文件:DbHelper.dll 和 DbHelper.XML。若项目引用多个dll,则需要将相关的项目的dll和注释xml文件都准备好.否则的话在帮助文件中将不能点击相关的类.(如果添加了一个类所在的项目dll和xml文件,则此类在chm文件中可以被点击,点击后跳转到此类的说明页面。)

三、生成帮助文件元数据：

安装完SandCastle后,会在其generic目录中找到GUI工具:SandcastleGui.exe，运行它生成一个sproj文件.经过SandCastle生成了chm文件的元数据文件,路径保存在:C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中.

四、使用HTML Help Workshop完善CHM文件：

在C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中有这三个文件:DbHelper.hhcDbHelper.hhkDbHelper.hhp运行HTML Help Workshop,可以打开XmlCommentDemo.hhp文件.单开文件后,单击"File"->"Compile...",单击"Compile",则会在.hhp的目录下生成.chm文件。DbHelper.chm就是最终文档.