Share via


© 2004 Microsoft Corporation. All rights reserved.

Figure 1 Configuring XML Comment Exploration

Figure 1 Configuring XML Comment Exploration

Figure 2 GiveHelpTransforms.cs Excerpt

  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();
        }

Figure 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>

Figure 4 GiveHelpDoc.xml Excerpt

  <?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>

Figure 5 Results of Tag Processing

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

Figure 6 Prefix Values

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
!:

Figure 7 cref Examples

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"

Figure 8 Type List

Figure 8 Type List

Figure 9 Extracting Type Name and Description

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

Figure 10 GiveTypeMemberListHelp.xsl

  <xsl:stylesheet xmlns:xsl="https://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>
•••

Figure 11 GiveTypeMemberHelp.xsl Excerpt

  <xsl:stylesheet xmlns:xsl="https://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>
•••

Figure 12 HTML Equivalent to XML Comments

.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

Figure 13 HTML for GiveHelpDoc.xml Excerpt

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0122)https://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="https://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="https://localhost/GiveHelp/   
                      GiveTypeMemberHelp.aspx?Type=GiveHelp.
                      GiveHelpTransforms&amp;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="https://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="https://localhost/GiveHelp/     
                  GiveTypeMemberHelp.aspx?Type=GiveHelp.
                  GiveHelpTransforms&amp;Member=GiveHelp.GiveHelpTransforms.
                  GiveTypeListHTMLHelp">
                  GiveHelpTransforms.GiveTypeListHTMLHelp</A> <DT></DT>
                  <DD>
                      <A href="https://localhost/GiveHelp/    
                      GiveTypeMemberHelp.aspx?Type=GiveHelp.
                      GiveHelpTransforms&amp;Member=GiveHelp.
                      GiveHelpTransforms.GiveMemberHTMLHelp(System.String)">
                      GiveHelpTransforms.GiveMemberHTMLHelp(System.String)
                      </A>
                  </DD>
              </DD>
          </DT>
      </DL>
  </BODY>
</HTML>