把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
2008-12-27 21:18
567 查看
原文出处：http://blog.csdn.net/xuxiaoping_cumt/archive/2005/11/17/531476.aspx
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
<!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 http-equiv="Content-Type" content="text/html; charset=utf-8"> <META content="MSHTML 6.00.2462.0" name="GENERATOR"> <META content="C#" name="CODE_LANGUAGE"> <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> <TD align="middle"> <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> <B>See Also:</B> <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> </DD> </DT> </DL> </BODY></HTML>
总结
虽然很早就已经有工具可以从源代码中提取注释，但是他们都没有被广泛的应用。原因大多都是使用复杂或者没有跟主流开发工具集成在一起。 C#中基于XML的注释，把语言跟工具很好的集成到一起，从而使使用xml注释l变得相当吸引人。
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
<!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 http-equiv="Content-Type" content="text/html; charset=utf-8"> <META content="MSHTML 6.00.2462.0" name="GENERATOR"> <META content="C#" name="CODE_LANGUAGE"> <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> <TD align="middle"> <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> <B>See Also:</B> <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> </DD> </DT> </DL> </BODY></HTML>
总结
虽然很早就已经有工具可以从源代码中提取注释，但是他们都没有被广泛的应用。原因大多都是使用复杂或者没有跟主流开发工具集成在一起。 C#中基于XML的注释，把语言跟工具很好的集成到一起，从而使使用xml注释l变得相当吸引人。
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 
相关文章推荐
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成
- 一个自动把Visual Studio.NET的C#，VB.NET，VC++project工程转为NAnt Build的小程序（利用XSL）
- 0120如何合并两个使用 System.Xml 使用 Visual C#.NET 的 XML 文档中的数据
- 如何用 Visual C#.net 中的 DTD、 XDR，或 XSD 验证 XML 文档
- 在Visual studi C#的“///”注释内容生成XML文档
- 在控制台编译Visual Studio .NET 2003的工程文件或解决方案文件
- HOW TO：在 Visual C# .NET 中使用 System.Xml 合并两个 XML 文档中的数据
- Visual Studio 2008（C#）XML注释提取成帮助文档的方法(转)
- C# XML 文档注释文件格式
- [导入]在 Visual Studio .NET IDE 内使用“从源代码管理打开”时出现无法读取项目文件的错误
- [导入]在 Visual Studio .NET IDE 内使用“从源代码管理打开”时出现无法读取项目文件的错误
- HOW TO：使用 Visual C# .NET 从文件中读取 XML
- C# : 操作Word文件的API - (将C# source中的xml注释转换成word文档)
- 使用 Visual C# .NET 从文件中读取 XML
- [导入]在 Visual Studio .NET IDE 内使用“从源代码管理打开”时出现无法读取项目文件的错误
- HOW TO：使用 Visual C# .NET 从文件中读取 XML
- 311530 HOW TO：在 Visual C# .NET 中使用 System.Xml 合并两个 XML 文档中的数据 (From MKBA)