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

作者: 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>
  <members>
    <member name="T:MyExampleClass">
      <remarks>
      This is my example class that does <b>nothing</b>.
      </remarks>
    </member>
    <member name="M:MyExampleMethod">
      <summary>
      This method just returns a string.
      </summary>
      <param name="strReturnThis">
      This is a string parameter that will just be returned. 
      </param>
      <returns>
      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>
    <assembly>
        <name>GiveHelp</name>
    </assembly>
    <members>
        <member name="T:GiveHelp.GiveHelpTransforms">
            <remarks>
              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>
                  <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\\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>
        ???
        <member name="P:GiveHelp.GiveHelpTransforms.SourceXML">
            <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
<exception>	The cref attribute is expanded
<permission>	The cref attribute is expanded
<seealso>	The cref attribute is expanded
<include>	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	T:
Field	Member variables	F:
Method	Procedures and functions	M:
Property	Properties	P:
Event	Events	E:
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>
    <name>Name</name>
  </assembly>
  <members>
    <member name="name">
      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>
        <TD align="center">
          <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>
        <B>See Also:</B>
        <DL>
            <xsl:apply-templates select="seealso" />
        </DL>
    </xsl:template>
    <xsl:template match="summary | remarks | value">
        <DT></DT>
        <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>
<paramref>	<I>
<see>	<A>
<list type="table">	<TABLE>
<list type="bullet">	<UL>
<list type="number">	<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

  1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  2 <!-- saved from url=(0122)http://localhost/GiveHelp/
  3 GiveTypeMemberHelp.aspx?Member=GiveHelp.GiveHelpTransforms.
  4   GiveMemberListHTMLHelp(System.String) -->
  5 <HTML>
  6   <HEAD>
  7       <META http-equiv="Content-Type" content="text/html; charset=utf-8">
  8       <META content="MSHTML 6.00.2462.0" name="GENERATOR">
  9       <META content="C#" name="CODE_LANGUAGE">
 10       <META content="JavaScript (ECMAScript)" 
 11         name="vs_defaultClientScript">
 12       <META content="http://schemas.microsoft.com/intellisense/ie5" 
 13         name="vs_targetSchema">
 14   </HEAD>
 15   <BODY>
 16       <TABLE cellSpacing="0" cellPadding="10" width="100%" 
 17         bgColor="lightskyblue" border="1">
 18           <TBODY>
 19               <TR>
 20                 <TD align="middle">
 21                       <H1>
 22                           Assembly: GiveHelp
 23                           <BR>
 24                           Type: GiveHelpTransforms
 25                       </H1>
 26                   </TD>
 27               </TR>
 28           </TBODY>
 29       </TABLE>
 30       <H2>
 31           Method
 32       </H2>
 33       <TABLE cellSpacing="0" cellPadding="10" width="100%" 
 34         bgColor="silver" border="1">
 35           <TBODY>
 36               <TR>
 37                   <TD>
 38                       <B>GiveMemberListHTMLHelp(System.String)</B>
 39                   </TD>
 40               </TR>
 41           </TBODY>
 42       </TABLE>
 43       <P>
 44       </P>
 45       <B>Description:</B>
 46       <DL>
 47       </DL>
 48       <DL>
 49           <DT>
 50               <DD>
 51                   Calling this function will take the XML in 
 52                     <A href="http://localhost/GiveHelp/   
 53                       GiveTypeMemberHelp.aspx?Type=GiveHelp.
 54                       GiveHelpTransforms&amp;Member=GiveHelp.
 55                       GiveHelpTransforms.SourceXML"> SourceXML</A>
 56                       and translate it to a list of 
 57                       Members in the specified type.
 58               </DD>
 59           </DT>
 60       </DL>
 61       <DL>
 62       </DL>
 63       <B>Permission:</B>
 64       <DL>
 65           <DT>
 66               <DD>
 67                   <DL>
 68                       <DT><A href="http://localhost/GiveHelp/
 69                            GiveTypeHelp.aspx?Type=."></A>
 70                           <DD>
 71                               public
 72                           </DD>
 73                       </DT>
 74                   </DL>
 75               </DD>
 76           </DT>
 77       </DL>
 78       <B>Parameters:</B>
 79       <DL>
 80           <DT>
 81               <DD>
 82                   <DL>
 83                       <DT><I>strType</I>
 84                           <DD>
 85                               The fully qualified name of the type that 
 86                               the member is in.
 87                           </DD>
 88                   </DL>
 89               </DD>
 90       </DL>
 91       <B>Returns:</B>
 92       <DL>
 93           <DT>
 94               <DD>
 95                   The HTML that lists the types that are in the 
 96                   XML documentation.
 97               </DD>
 98           </DT>
 99       </DL>
100       <B>Exceptions:</B>
101       <DL>
102       </DL>
103       <B>Example:</B>
104       <DL>
105           <DT>
106               <DD>
107                   <PRE> // create the class that does translations
108           
109           GiveHelpTransforms ght = new GiveHelpTransforms();
110           // have it load our XML into the SourceXML property
111           ght.LoadXMLFromFile(
112                   "E:\\Inetpub\\wwwroot\\GiveHelp\\GiveHelpDoc.xml");
113             
114           // do the translation and then write out the string
115           Response.Write( 
116               ght.GiveMemberListHTMLHelp(Request.QueryString.Get("Type")));
117           </PRE>
118         </DD>
119       </DT>
120       </DL>
121       <B>See Also:</B>
122       <DL>
123           <DT>
124               <DD>
125                   <A href="http://localhost/GiveHelp/     
126                   GiveTypeMemberHelp.aspx?Type=GiveHelp.
127                   GiveHelpTransforms&amp;Member=GiveHelp.GiveHelpTransforms.
128                   GiveTypeListHTMLHelp">
129                   GiveHelpTransforms.GiveTypeListHTMLHelp</A> <DT></DT>
130                   <DD>
131                       <A href="http://localhost/GiveHelp/    
132                       GiveTypeMemberHelp.aspx?Type=GiveHelp.
133                       GiveHelpTransforms&amp;Member=GiveHelp.
134                       GiveHelpTransforms.GiveMemberHTMLHelp(System.String)">
135                       GiveHelpTransforms.GiveMemberHTMLHelp(System.String)
136                       </A>
137                   </DD>
138               </DD>
139           </DT>
140       </DL>
141   </BODY>
142 </HTML>

总结

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

作者Blog：http://blog.csdn.net/carper/