把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档

PRE { background:#EEEEEE; margin-top:1em; margin-bottom:1em; margin-left:0px; padding:5pt; font-size:90%; font-family:'courier new',courier,serif; }

作者: J. Andrew Schafer

这篇文章假设你对 XML, XSLT, 和 C# 熟悉

下载这篇文章的源代码: XMLC.exe (76KB)

译者说明：这篇文章是很早以前就发表了，它提供的源代码是基于 VS.net 测试版（RTM 和 Beta 2）的。

摘要

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

为何不把这些信息保存在一个地方呢？？最明显想到的地方就是代码的注释中；但是你很难通览程序，并且有些需要这些文档的人并不懂编码。

这篇文章将展示如何通过使用XML注释来解决这些问题。代码注释、用户手册、开发人员手册、测试计划等很多文档可以很方便的从XML注释中获得。我将先演示如何插入XML注释、如何把这些XML注释导出为另一个文档。然后再讨论每个XML标记的意思，以及使用XML和XSL生成帮助文件。

XML 注释

所有的XML注释都在三个向前的斜线之后(///)。两条斜线表示是一个注释，编译器将忽略后面的内容。三条斜线告诉编译器，后面是XML注释，需要适当地处理。

当开发人员输入三个向前的斜线后，Microsoft Visual Studio .NET IDE 自动检查它是否在类或者类成员的定义的前面。如果是的话，Visual Studio .NET IDE 将自动插入注释标记，开发人员只需要增加些额外的标记和值。下面就是在成员函数前增加三个斜线，自动增加的注释：

/// <summary>

///

/// </summary>

/// <param name="strFilePath"></param>

public void LoadXMLFromFile(string strFilePath)

这里嵌入的标记仅仅是Visual Studio .NET IDE 的一部分标记，然而在IntelliSense for xml中，并没有把c#规范中所有的标记列出来，遗失的部分只能用手工插入。

这些手工标记是非常有用的，如果恰当地设置他们，对导出成外部说明文件将非常有帮助。

如果碰到是预先定义的xml标记，编译器可以把这些注释以文本输出；如果是编译器不认识的xml标记，编译器会逐字的把所有内容都输出，这意味着你可以使用自己定义的标记。

适当的设置，C#编译器并不格式化xml注释，而是以xml文件输出。下面的步骤将演示如何让C#编译器把xml注释输出为xml文件

右键点击解决方案资源管理器中的工程项，打开工程的属性页，点击属性。

对话框出现后，点击配置属性目录。

点击生成节点。

在右边的框中有输出--xml文档文件，这里就是设置丛xml注释生成xml文件的文件名。（注：这里设置的是相对路径，不是绝对路径）在我的例子中，我使用GiveHelpDoc.xml作为文档名(看图一)。如果这里没有输入任何值，这将是默认设置，xml注释将不会以外部文件形式输出。

图一配置xml注释输出

公认的标记

我把xml注释标记分类两大类：第一类是设置标记，我叫他们主标记。他们在一组标记的开始，而且不会在标记内部出现。第二类是设置标记包含的标记，我叫他们支持标记。支持标记和html标记的区别在于：支持标记采用的是小写，html标记采用的是大写。图2显示了我将要讨论的支持标记和主标记。

图2 GiveHelpTransforms.cs 部分代码

namespace GiveHelp

{

/// <remarks>

/// Class that contains functions to do transformations to help files.

/// The source XML is loaded into the <see cref="SourceXML"/> property

/// (e.g. <c><I>obj</I>.SourceXML = "<I>XML goes here</I>"</c>). One of

/// the associated member functions (<see cref="GiveTypeListHTMLHelp"/

/// >, <see cref="GiveMemberListHTMLHelp"/>, <see

/// cref="GiveMemberHTMLHelp"/>)

/// is called to initiate and then return the transformation.

/// <para>

/// <list type="table">

/// <listheader>

/// <term>Help Page</term>

/// <description>Function to call</description>

/// </listheader>

/// <item><term>List of Types</term>

/// <description>GiveTypeListHTMLHelp</description></item>

/// <item><term>List of members</term>

/// <description>GiveMemberListHTMLHelp</description></item>

/// <item><term>Help for a single member</term>

/// <description>GiveMemberHTMLHelp</description></item>

/// </list>

/// </para>

/// </remarks>

/// <permission cref="">public</permission>

/// <example><code>

/// // create the class that does translations

/// GiveHelpTransforms ght = new GiveHelpTransforms();

/// // have it load our XML into the SourceXML property

/// ght.LoadXMLFromFile("E:\\Inetpub\\www-

/// root\\GiveHelp\\GiveHelpDoc.xml");

///

/// // do the translation and then write out the string

/// Response.Write( ght.

/// GiveMemberHTMLHelp(Request.QueryString.Get("Type"),

/// Request.QueryString.Get("Member")) );

/// </code></example>

public class GiveHelpTransforms

{

???

/// <summary>

/// Calling this function will take the XML in <see

/// cref="SourceXML"/>

/// and translate it to a list of Members in the specified type.

/// </summary>

/// <param name="strType">The fully qualified name of the type that

/// the member is in.</param>

/// <returns>The HTML that lists the types that are in the XML

/// documentation.</returns>

/// <seealso cref="GiveTypeListHTMLHelp"/>

/// <seealso cref="GiveMemberHTMLHelp"/>

/// <example><code>

/// // create the class that does translations

/// GiveHelpTransforms ght = new GiveHelpTransforms();

/// // have it load our XML into the SourceXML property

/// ght.LoadXMLFromFile(

/// "E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");

///

/// // do the translation and then write out the string

/// Response.Write(

/// ght.GiveMemberListHTMLHelp(Request.

/// QueryString.Get("Type")));

/// </code></example>

/// <permission cref="">public</permission>

public string GiveMemberListHTMLHelp(string strType)

{

// Load the corresponding XSLT

XslTransform xslTransformFile = new XslTransform();

xslTransformFile.Load(

"E:\\Inetpub\\wwwroot\\GiveHelp\\GiveTypeMemberListHelp.xsl");

// create the output repository for the transform

System.Text.StringBuilder sbTransformed =

new System.Text.StringBuilder();

System.IO.TextWriter tw =

(System.IO.TextWriter)new

System.IO.StringWriter(sbTransformed);

// the strType parameter is passed into the stylesheet

XsltArgumentList arglist = new XsltArgumentList();

arglist.AddParam("WhichType","",strType);

xslTransformFile.Transform(m_xdSourceXML,arglist,tw);

return tw.ToString();

}

这里有九个主标记： <remarks>, <summary>, <example>, <exception>, <param>, <permission>, <returns>, <seealso>, 和<include>.

在上下文中，<remarks>描述了这个类的细节。

/// <remarks>

/// Class that contains functions to do

/// transformations to help files.

/// </remarks>

C#文档推荐使用<remarks>描述一个对象，<summary>描述一个对象成员。奇怪的是如果你用Visual Studio .NET IDE在一个类前输入///，他将自动增加<summary>，而不是<remarks> ，这时你需要手工输入<remarks>。

<summary>经常在C#文档中发现，这个标记用于描述类的成员，包括属性、方法、成员等。

/// <summary>

/// This XmlDocument based attribute contains the

/// XML documentation for the project.

/// </summary>

<summary>也可以很好的描述对象，但是不推荐，xml注释文档推荐使用<remarks>描述对象。

<example>被用来演示如何使用，例子可以使任何正确的文本文件，但是更多是一小段代码：

/// <example>

/// <code>

/// // create the class that does translations

/// GiveHelpTransforms ght = new GiveHelpTransforms();

/// // have it load our XML into the SourceXML property

/// ght.LoadXMLFromFile(

/// "E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");

/// </code>

/// </example>

如果其中有代码，<code>经常被使用，<code>是将要被支持的一个标记。

<exception>处理异常文档。如果多于一个异常会被抛出，你就需要多个<exception>。 <exception>有一个属性：cref 这个属性值是将被扔出异常的类名。这个类名必须是正确的，因为C#编译器将检查这一项，后面我将具体讨论。

这篇文章的代码将不会扔出任何异常，但是下面有个代码例子，演示如何使用<exception>：

/// <exception cref="SampleException">

/// Normally, a discussion on any exceptions thrown would go here.

/// </exception>

<param>用于描述方法、属性的参数。当你在一个方法前面输入/// 他会被自动的插入。<param>有个属性，name 用于记录源代码中参数的名字。

/// <param name="strFilePath">The path to the file containing the

/// source XML.</param>

类成员访问修饰符是通过 <permission>来记录，它的值用来写明访问限制，值不是必需的。值可以是下面几种：public, private, protected等。Scope 是另外一个标记，用于表示是不是static的方法。

<permission>有个属性cref。cref 属性的值用来表示调用当前编译环境的一个类成员或者属性，它通常在System.Security.PermissionSet中定义。

/// <permission cref="System.Security.PermissionSet">Public

/// Access</permission>

<returns>跟 <param> 相类似，他用来描述方法、属性的返回值。

/// <returns>The HTML for a list of types based on the XML

/// documentation.</returns>

<seealso>同一个话题中的其他连接。这个标记通常没有值，仅仅有一个cref属性指向需要引用的对象名。这个属性可以是类、成员等等。

/// <seealso cref="GiveMemberListHTMLHelp"/>

XML compiler可以识别这些符号和内容，并把它转为xml文档，我将在稍后讨论这些xml文档文件。

当编译器从代码中提取xml注释的时候，任何使用<include>标识的文件都将被包含入注释，就像这些文件本来就在注释里面一样。因为编译器可以这样提取外部文件为注释，所以你可以把你的注释放到代码文件之外。不过这些注释并不很直观，因此，我从来不使用<include>。但是如果你的注释太长的话，你可以权衡一下。

<include>的几个用于指定外部文件的属性是必需的。file属性的值必须是绝对或相对文件路径，这个文件必须是一个包含xml注释的xml文件；path属性是用于指定xml注释位置的XPath路径。就像下面代码演示的：

/// <include file='MyXMLCommentFile.xml'

/// path='doc/members/member[@name="T:MyExampleClass"]/*'/>

public class MyExampleClass

{

/// <include file='MyXMLCommentFile.xml'

/// path='doc/members/member[@name="M:MyExampleMethod"]/*'/>

public string MyExampleMethod(string strReturnThis)

{

return strReturnThis;

}

图 3 MyXMLCommentFile.xml

<doc>

This is my example class that does <b>nothing</b>.

</remarks>

</member>

This method just returns a string.

</summary>

This is a string parameter that will just be returned.

</param>

Just returns the input parameter.

</returns>

</member>

</members>

</doc>

图3展示了MyXMLCommentFile.xml的代码。注意，我使用XPath指定注释中的位置。这个文件实际格式是开发人员自己定的，我更倾向于这个文件跟编译器产生的文件格式是一样的。

支持标记

这里使用了11个支持标记： <c>, <code>, <list>, <listheader>, <item>, <term>, <description>, <para>, <paramref>, <see>, 和<value>.

<c> 用于标记一行代码，它通常是用在描述性文本中。

/// The source XML is loaded into the <see cref="SourceXML"/>

/// property (e.g. <c><I>obj</I>.SourceXML =

/// "<I>XML goes here</I>"</c>).

<code>用于标识一段代码，它经常用在<example>中间， <code>跟<c>很相似。不同之处在于：<code>用于一段代码，<c>用于一行代码。他们都是用于指明期间的代码文本需要保留格式。

/// <code>

/// // create the class that does translations

/// GiveHelpTransforms ght = new GiveHelpTransforms();

/// // have it load our XML into the SourceXML property

/// ght.LoadXMLFromFile(

/// "E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");

/// </code>

<list>是用于定义一个表格的注释标记。<list>的type属性可以有下面三个值：bullet、number或者 table。<list>内有些其他的标记，就如下面代码演示的：

/// <list type="table">

/// <listheader>

/// <term>Help Page</term>

/// <description>Function to call</description>

/// </listheader>

/// <item><term>List of Types</term>

/// <description>GiveTypeListHTMLHelp</description></item>

/// <item><term>List of members</term>

/// <description>GiveMemberListHTMLHelp</description></item>

/// <item><term>Help for a single member</term>

/// <description>GiveMemberHTMLHelp</description></item>

/// </list>

<listheader>用于记录list 的刊头信息（看上面的例子）。最有代表性的是使用table类型的list标记。

正如你所料，<item>定义list的每一个项目，它可以单独使用或者和<term> 与 <description> 一起混用。 <term> 与 <description>是<listheader> 或者 <item>的子标记。它们通常一起使用。

<para>标记用于新的段落，他跟html的<p>非常相似。在长段的注释中，你应该用这个标记把它拆分开。

/// <summary>This is a summary.

/// <para>This is a new paragraph.</para>

/// </summary>

如果注释文本中需要特别强调一个参数，那就用<paramref>。在需要的地方插入这个标记，这个标记的作用是突出参数的名字。

/// Loads the XML documentation in the file specified by

/// <paramref>strFilePath</paramref>.

<see>作为一个超链接用在其他标记之内。它在文本中使用，通常只有一个属性cref。

/// One of the associated member functions (<see

/// cref="GiveTypeListHTMLHelp"/>,

/// <see cref="GiveMemberListHTMLHelp"/>, <see

/// cref="GiveMemberHTMLHelp"/>)

/// is called to initiate and then return the transformation.

cref 指定一个已存在的引用，更多信息看<exception>的描述。

<value>用于定义类属性，就像<remarks>定义类，<summary>定义其他成员一样。

/// <value>

/// The SourceXML property contains the XML that will be used in

/// the transformations by the member functions for this class.

/// </value>

XML文档文件

前面，我解释了在生成工程的时候，如何输出xml注释为xml文件，

其中图4展示了我生成工程同时生成xml文档的一部分内容。如果你比较图2和图4，你会注意到，图2中原始的xml注释已经被整理为图4的xml文档。

图 4 GiveHelpDoc.xml 部分代码

<?xml version="1.0"?>

<doc>

<name>GiveHelp</name>

</assembly>

Class that contains functions to do transformations to help

files. The source XML is loaded into the <see

cref="P:GiveHelp.GiveHelpTransforms.SourceXML"/> property

(e.g. <c><I>obj</I>.SourceXML = "<I>XML goes here</I>"

</c>). One of the associated member functions (<see

cref="M:GiveHelp.GiveHelpTransforms.GiveTypeListHTMLHelp"

/>, <see cref="M:GiveHelp.GiveHelpTransforms.

GiveMemberListHTMLHelp(System.String)"/>, <see

cref="M:GiveHelp.GiveHelpTransforms.GiveMemberHTMLHelp

(System.String)"/>) is called to initiate and then return

the transformation.

<para>

<description>Function to call</description>

</listheader>

<item><term>List of Types</term>

<description>GiveTypeListHTMLHelp</description></item>

<item><term>List of members</term>

<description>GiveMemberListHTMLHelp</description>

</item>

<item><term>Help for a single member</term>

<description>GiveMemberHTMLHelp</description></item>

</list>

</para>

</remarks>

<permission cref="!:">public</permission>

// create the class that does translations

GiveHelpTransforms ght = new GiveHelpTransforms();

// have it load our XML into the SourceXML property

ght.LoadXMLFromFile

("E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");

// do the translation and then write out the string

Response.Write(

ght.GiveMemberHTMLHelp(Request.QueryString.Get("Type"),

Request.QueryString.Get("Member")) );

</code></example>

</member>

???

<value>

The SourceXML property contains the XML that will be used in

the transformations by the member functions for this class.

</value>

<permission cref="!:">public</permission>

</member>

</members>

</doc>

图5中，显示了需要特殊处理的标记处理后的效果。这儿罗列的所有标记几乎都是按照cref属性进行了转换。这意味着C#解析器对cref属性的原始值做了两件事：第一，他对这个可能是类或者属性的值进行了分类。第二，他处理这些值。

图 5 标记被处理的结果

Tag

Result

The cref attribute is expanded

The cref attribute is expanded

The cref attribute is expanded

The reference tags are copied into the documentation file

<see>

The cref attribute is expanded

例如：一个cref 值是"MyMember"的属性(这就是 cref="MyMember")。解析器会把它解析为：

M:MyProject.MyType.MyMember

M:是个分级描述，编译器把xml文档中涉及到的成员分成5类，这些分类是以文档中涉及到的成员名称的前缀命名的。图6显示了这个关系。

图 6 前缀值对应关系

Meaning

When Used

Prefix

Type

Classes, delegates

Field

Member variables

Method

Procedures and functions

Property

Properties

Event

Events

Unknown

A reference that cannot be qualified

前面例子中扩展名的其他部分也是有意义的。"MyNamespace.MyType.MyMember"这个值是一个能够被C#编译器找到的完全名称，这个名称可以使用分隔符分成几部分，每一部分都有它对应的意思："MyNamespace" 对应名称空间，"MyType"对应类，"MyMember"对应成员。

如果cref的值不能被找到的话，编译器将用"!:" 来作为前缀。（看图7）

图 7 cref 例子

cref Value

Expanded Name

cref="MyClass"

"T:MyProject.MyClass"

cref="MyField"

"F:MyProject.MyClass.MyField"

cref="MyMethod"

"M:MyProject.MyClass.MyMethod"

cref="MyProperty"

"E:MyProject.MyClass.MyProperty"

cref="MyEvent"

"P:MyProject.MyClass.MyEvent"

cref="MyUnknown"

"!:MyUnknown"

cref 的属性不仅在上面的解码中用，它的成员名在转换为xml文档中也被使用，就像你下面要看到的。

<?xml version="1.0"?>

<doc>

</assembly>

XML Comments are here

</member>

...

</members>

</doc>

第一行是标准的头，下面是根标记<doc>。在下面是<assembly>。在<assembly> 里面是<name>。<name>是代码所生成工程的程序集名，因此通常只有一个<name> 条目。这个值通常是C#编译器提取的工程名，它与代码中的xml注释没有任何关系。

接下来是<members>，它包含每一个有联系的xml注释，每一个成员都有一个它自己的<member>。

<member>有个属性name，C# 解析器获得关联xml注释对应的成员名字作为这个属性的值。我已经描述过这个值的命名规范，剩下的由<member>所包含的xml由实际的代码文件中的xml注释所组成，前面我已经提及。

产生帮助文件

一个文档罗列所有xml注释几乎是不可能的，通常我们使用XSLT去解析XML为 Html 帮助页面。

我新建了一个名叫GiveHelp的工程，它里面包含一个简单的名叫GiveHelpTransforms 的类、几个asp.net页面和转换为html用的XSLT文件。（文章开头有源代码下载链接）。这个Web应用把本地xml文件转换为一个帮助文件。

这些asp.net页面把转换后的结果在浏览器中展现，他们使用了GiveHelpTransforms类的接口去转换xml为html。

采用GiveHelpTransforms类有两个理由：首先，其他工程也可以利用这个代码实现从xml到html的转换；其次，在这个示范工程中，我需要一个类来演示这个转换。听起来有些混乱，但是通过我的例子演示，你就会知道该如何做。

转换

在这一节中，我假设你已经了解了XSLT，因此我只是简单的讲如何把xml文档转换为html。

我把帮助系统分作三层，最顶层是类列表。这个页面罗列xml文档中所有的类的细节信息，演示看图8。

图 8 类列表页面

类列表页的每一个类的链接都到一个类的所有成员列表的页面。中间层是类成员列表页，这个页面将罗列这个类的所有成员和他们的具体信息。点击一个成员链接，将进入下一层，类成员页。那里罗列类成员的细节、许可、参数、异常、例子和一些其他链接。

这一节中使用的XSLT是GiveTypeHelp.xsl文件。它在浏览器中把xml转换为罗列所有的类的html。使用一对<Dl>来创建类定义表，类的名称被放在<DT>中，详细说明将放在<DD>中，页面左边显示了类名，下面是详细介绍。

类名被从文档中萃取。你应该还记得所有的类的名字前缀是"T:" ，于是 xslt应该这样写：

<xsl:apply-templates select="./members/member[starts-with

(@name,'T:')]" />

这一行能够在代码块的头找到<doc>元素，以后代码会被找到就像下面：

<xsl:template match="member[starts-with(@name,'T:')]">

...

</xsl:template>

这个是被<xsl:apply-templates>调用，这两个声明告诉XSLT解析器，仅仅提取满足上述条件的成员。

把每个类转换为html页，每个类的名字从name属性中获得，然后每个类的细节描述被提取。图9演示了如何利用<DT> 和 <DD>处理

图 9 提取类的名字和细节

<DT>

<A>

<xsl:attribute name="href">

GiveTypeMemberListHelp.aspx?Type=<xsl:value-of select="substring-

after(@name,':')" />

</xsl:attribute>

<B>

<xsl:value-of select="substring-after(@name,'.')" />

</B>

</A>

</DT>

<DD>

<xsl:apply-templates select="remarks | summary" />

</DD>

在<DT>中，一个指向具体类信息的超链接被创建。在<DD>中，<remarks> 或者 <summary>值被提取。下一节我将解释XSLT做了那些处理，图8就是显示了处理结果。

成员列表

我的例子中，在类列表那一页面，如果一个类被点击，页面将跳转到GiveTypeMemberListHelp.aspx页面，这个页面罗列了该类的所有成员。图 10 是对XSLT的一段摘录，更详细的看源代码。

图 10 GiveTypeMemberListHelp.xsl

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

version="1.0">

<xsl:output method="html" />

<xsl:param name="WhichType" />

<xsl:template match="doc">

<xsl:apply-templates select="./assembly/name" />

<H2>

Members

</H2>

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('F:',$WhichType))]" mode="fields" />

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('P:',$WhichType))]" mode="properties" />

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('M:',$WhichType))]" mode="methods" />

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('E:',$WhichType))]" mode="events" />

</xsl:template>

<xsl:template match="name">

<TABLE width="100%" border="1" cellspacing="0" cellpadding="10"

bgcolor="lightskyblue">

<TR>

<H1>

<xsl:text>Assembly: </xsl:text>

<xsl:value-of select="." />

<BR />

<xsl:text>Type: </xsl:text>

<xsl:value-of select="substring-after($WhichType,'.')" />

</H1>

</TD>

</TR>

</TABLE>

</xsl:template>

<xsl:template match="member" mode="methods">

<xsl:if test="position() = 1">

<P></P>

<H3>Methods</H3>

</xsl:if>

<DL>

<DT>

<A>

<xsl:attribute name="href">

GiveTypeMemberHelp.aspx?

Member=<xsl:value-of select="substring-after(@name,':')" />

</xsl:attribute>

<B>

<xsl:value-of select="substring-

after(@name,concat($WhichType,'.'))" />

</B>

</A>

</DT>

<DD>

<xsl:apply-templates select="remarks | summary" />

</DD>

</DL>

<P></P>

</xsl:template>

...

当GiveTypeMemberListHelp.aspx 页面被请求的时候，它接受了一个完全的类名GET参数。（比如：/GiveTypeMemberListHelp.aspx?Type=MyNamespace.MyType）在XML-to-HTML的转换过程中，XSLT把这个值传递给XSLT的参数：WhichType。这个XSLT的参数如下：

<xsl:param name="WhichType" />

这个参数用在过滤 <member>。下面是XSLT的具体做法：

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('F:',$WhichType))]" mode="fields" />

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('P:',$WhichType))]" mode="properties" />

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('M:',$WhichType))]" mode="methods" />

<xsl:apply-templates select="./members/member[starts-

with(@name,concat('E:',$WhichType))]" mode="events" />

代码很明确，它是调用<member>的 Fields, Properties, Methods 和 Events 模板。我使用XPath 来实现这个功能，Xpath的参数就如下：

*:Namespace.Type.Member

每个成员的调用模板都很相似，我来解释一下GiveTypeMemberListHelp.xsl 中的模板(看图10)。 <xsl:if> 这个标记用来判断是不是满足条件，如果满足,将被写到 <DT>中间的部分。 <DD>中间的部分是来自于<summary> 或 <remarks>的部分数据.

类成员

这一节的讨论在 GiveTypeMemberHelp.xsl 文件中。就像类成员列表那一层，类成员层也有一个参数，这个参数就是类成员的全名。 <xsl:param name="WhichMember" />

类可以从类成员全名中获得，于是你可以看到下面的XSLT: <xsl:param name="WhichType" select="concat

(concat( substring-before($WhichMember,'.'), '.'),

substring-before(substring-after($WhichMember,'.'),'.'))" />

XSLT 的开头部分要比上一个要复杂些： <xsl:template match="doc">

<xsl:apply-templates select="./assembly/name" />

<xsl:apply-templates select="./members/member[contains

(@name,$WhichMember)]" />

</xsl:template>

第一个<xsl:apply-templates> 是从<name>中提取数据；第二个<xsl:apply-templates> 是提取满足$WhichMember的类成员。下面这一行是从图11中提取的处理成员注释的部分。 <xsl:template match="member[contains(@name,$WhichMember)]">

图 11 GiveTypeMemberHelp.xsl 摘录 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:output method="html" />

<xsl:param name="WhichMember" />

<xsl:param name="WhichType" select="concat(concat( substring-

before($WhichMember,'.'), '.'), substring-before(substring-

after($WhichMember,'.'),'.'))" />

<xsl:template match="doc">

<xsl:apply-templates select="./assembly/name" />

<xsl:apply-templates select="./members/

member[contains(@name,$WhichMember)]" />

</xsl:template>

<xsl:template match="name">

...

</xsl:template>

<xsl:template match="member[contains(@name,$WhichMember)]">

<H2>

<xsl:choose>

<xsl:when test="starts-with(@name,'M:')">

Method

</xsl:when>

<xsl:when test="starts-with(@name,'F:')">

Field

</xsl:when>

<xsl:when test="starts-with(@name,'P:')">

Property

</xsl:when>

<xsl:when test="starts-with(@name,'E:')">

Event

</xsl:when>

</xsl:choose>

</H2>

<TABLE width="100%" border="1" cellspacing="0" cellpadding="10"

bgcolor="silver">

<TR>

<TD>

<B>

<xsl:value-of select="substring-

after($WhichMember,concat($WhichType,'.'))" />

</B>

</TD>

</TR>

</TABLE>

<P></P>

<B>Description:</B>

<DL>

<xsl:apply-templates select="remarks" />

</DL>

<DL>

<xsl:apply-templates select="summary" />

</DL>

<DL>

<xsl:apply-templates select="value" />

</DL>

<B>Permission:</B>

<DL>

<xsl:apply-templates select="permission" />

</DL>

<xsl:if test="not(starts-with(@name,'F:'))">

<B>Parameters:</B>

<DL>

<xsl:apply-templates select="param" />

</DL>

<xsl:if test="not(starts-with(@name,'E:')) and not(starts-

with(@name,'P:'))">

<B>Returns:</B>

<DL>

<xsl:apply-templates select="returns" />

</DL>

</xsl:if>

<B>Exceptions:</B>

<DL>

<xsl:apply-templates select="exception" />

</DL>

</xsl:if>

<B>Example:</B>

<DL>

<xsl:apply-templates select="example" />

</DL>

<DL>

<xsl:apply-templates select="seealso" />

</DL>

</xsl:template>

<xsl:template match="summary | remarks | value">

<DD>

<xsl:apply-templates />

</DD>

</xsl:template>

...

<xsl:template match="*">

<xsl:copy>

<xsl:apply-templates />

</xsl:copy>

</xsl:template>

</xsl:stylesheet>

...

如果你对XSLT比较熟悉，这些都是很简单的。

除了插入不同的标记以外，属于这个成员的标记也会被处理。他们是通过<xsl:apply-templates select="summary" /> 和 <xsl:apply-templates select= "param" />来处理的。你可以在GiveTypeMemberHelp.xsl中找到代码。

处理标记

处理完文档的标记之后，开始处理xml注释，这个处理过程在工程中随处可见。

在不同的处理中，主标记会分别不同。在类列表和类成员列表中，它是<summary> 和 <remarks>。在类成员层，它是primary tag 你可以在XSLT文件中看到： <xsl:apply-templates select="primary tag" "primary tag" 被作为主标记。

一旦被执行，就像下面，进程会跳转到对应块。 <xsl:template match="primary tag">

...

<xsl:apply-templates />

...

</xsl:template>

在primary tag 附近的html标记将通过<xsl:apply-templates />来创建。

这些支持的标记在转换中通常被转为html标记。例如<c> 就是做下面的转换。

<xsl:template match="c">

<CODE>

<xsl:apply-templates />

</CODE>

</xsl:template>

Xml注释中的 <c> 对应 html 中的 <CODE>。更多的对应关系看图12。

图 12 XML 注释标签与HTML对应关系

.NET XML Comment Tag

My HTML Equivalent

<c>

<CODE>

<para>

<P>

<I>

<see>

<A>

<TABLE>

<UL>

<OL>

<listheader> (with table)

<THEAD>

<listheader> (with list)

<LI><B>

<item> (with table and in header)

<TR>[<TH>]

<item> (with table)

<TR>[<TD>]

<item> (with list)

<LI>

<term> (with table and in header)

<TH>

<term> (with table)

<TD>

<term> (with list)

Special: adds "-" to end of tag value

<description> (with table and in header )

<TH>

<description> (with table)

<TD>

<description> (with list)

None

<code>

<PRE>

Special: all other nodes are just copied in

图13演示了xml（图4）通过XSLT（图11中的XSLT）转换为html。

图 13 转换为html后的GiveHelpDoc.xml

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<!-- saved from url=(0122)http://localhost/GiveHelp/

GiveTypeMemberHelp.aspx?Member=GiveHelp.GiveHelpTransforms.

GiveMemberListHTMLHelp(System.String) -->

<HTML>

<HEAD>

<META content="JavaScript (ECMAScript)"

name="vs_defaultClientScript">

<META content="http://schemas.microsoft.com/intellisense/ie5"

name="vs_targetSchema">

</HEAD>

<BODY>

<TABLE cellSpacing="0" cellPadding="10" width="100%"

bgColor="lightskyblue" border="1">

<TBODY>

<TR>

<H1>

Assembly: GiveHelp

<BR>

Type: GiveHelpTransforms

</H1>

</TD>

</TR>

</TBODY>

</TABLE>

<H2>

Method

</H2>

<TABLE cellSpacing="0" cellPadding="10" width="100%"

bgColor="silver" border="1">

<TBODY>

<TR>

<TD>

<B>GiveMemberListHTMLHelp(System.String)</B>

</TD>

</TR>

</TBODY>

</TABLE>

<P>

</P>

<B>Description:</B>

<DL>

</DL>

<DL>

<DT>

<DD>

Calling this function will take the XML in

<A href="http://localhost/GiveHelp/

GiveTypeMemberHelp.aspx?Type=GiveHelp.

GiveHelpTransforms&Member=GiveHelp.

GiveHelpTransforms.SourceXML"> SourceXML</A>

and translate it to a list of

Members in the specified type.

</DD>

</DT>

</DL>

<DL>

</DL>

<B>Permission:</B>

<DL>

<DT>

<DD>

<DL>

<DT><A href="http://localhost/GiveHelp/

GiveTypeHelp.aspx?Type=."></A>

<DD>

public

</DD>

</DT>

</DL>

</DD>

</DT>

</DL>

<B>Parameters:</B>

<DL>

<DT>

<DD>

<DL>

<DT><I>strType</I>

<DD>

The fully qualified name of the type that

the member is in.

</DD>

</DL>

</DD>

</DL>

<B>Returns:</B>

<DL>

<DT>

<DD>

The HTML that lists the types that are in the

XML documentation.

</DD>

</DT>

</DL>

<B>Exceptions:</B>

<DL>

</DL>

<B>Example:</B>

<DL>

<DT>

<DD>

<PRE> // create the class that does translations

GiveHelpTransforms ght = new GiveHelpTransforms();

// have it load our XML into the SourceXML property

ght.LoadXMLFromFile(

"E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");

// do the translation and then write out the string

Response.Write(

ght.GiveMemberListHTMLHelp(Request.QueryString.Get("Type")));

</PRE>

</DD>

</DT>

</DL>

<DL>

<DT>

<DD>

<A href="http://localhost/GiveHelp/

GiveTypeMemberHelp.aspx?Type=GiveHelp.

GiveHelpTransforms&Member=GiveHelp.GiveHelpTransforms.

GiveTypeListHTMLHelp">

GiveHelpTransforms.GiveTypeListHTMLHelp</A> <DT></DT>

<DD>

<A href="http://localhost/GiveHelp/

GiveTypeMemberHelp.aspx?Type=GiveHelp.

GiveHelpTransforms&Member=GiveHelp.

GiveHelpTransforms.GiveMemberHTMLHelp(System.String)">

GiveHelpTransforms.GiveMemberHTMLHelp(System.String)

</A>

</DD>

</DT>

</DL>

</BODY>

</HTML>

总结

虽然很早就已经有工具可以从源代码中提取注释，但是他们都没有被广泛的应用。原因大多都是使用复杂或者没有跟主流开发工具集成在一起。 C#中基于XML的注释，把语言跟工具很好的集成到一起，从而使使用xml注释l变得相当吸引人。