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 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="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>
•••
Figure 11 GiveTypeMemberHelp.xsl Excerpt
<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>
•••
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)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>
|