Wouldn’t it be nice if all this information were kept in one location? The obvious place to put this information is in the source code itself; this makes it easy to modify the docs along with the code. But it is hard enough to go through someone else’s program when you know how to code, let alone when you are less technically savvy. Also, adding code documentation takes time.
This article will show you how to solve many of those problems using XML comments. Code comments, user manuals, developer manuals, test plans, and many other documents can be generated from a single source using XML tags. I’ll explain how to insert XML comments and enable exportation of these comments to another file. I’ll then discuss each of the available tags and the format of the XML file where the tags are used and walk through an example of using XML comments and XSLT to generate help files.

XML Comments

All XML comments begin with three forward slashes (///). The first two slashes signify a comment and tell the compiler to ignore the text that follows. The third slash tells the parser that this is an XML comment and should be handled appropriately.
      When the developer types the three forward slashes, the Microsoft® Visual Studio® .NET IDE checks to see if it precedes an identifiable type or type member definition. If it is identifiable, then the Visual Studio .NET IDE will automatically insert a few comment tags. The developer then adds additional tags and values as needed. For example, here are the XML tags that are generated when the three forward slashes are entered before this member function that has a parameter:

/// <summary>
///
/// </summary>
/// <param name="strFilePath"></param>
public void LoadXMLFromFile(string strFilePath)

The tags inserted here represent only a couple of many that the Visual Studio .NET IDE already knows.

While the current implementation of IntelliSense® for XML comments does not show all the tags listed in the C# specification, the missing tags can always be inserted manually.

      Once comments are inserted, it would be useful to do something with them. If you set things up correctly (as I’ll explain shortly), this usually just means exporting all the text that comes after the three forward slashes into an external file.

      There are also several predefined XML comment tags that the parser knows. When these tags are encountered (and have been used correctly by the developer), the parser will format the tags’ output to a text file. If a tag that is not predefined is encountered, it is just written verbatim along with any text to the external file. This means that you can make up your own tags or you can even use known tags recognizable from another source (such as HTML) in the comments.

      When exportation is set up correctly, the C# parser extracts the XML comments, does formatting if needed, and places them into an XML file of your choice. You can set the location and file name of the XML document file, and enable exportation, through your project’s property pages. To do this, follow these four steps:

• Open the property page for the project, usually by right-clicking on the project in the Solution Explorer, and click Properties.
• After the dialog has opened, click the Configuration Properties folder.
• Click the Build option.
• In the right pane, there will be a property field called XML Documentation File. Set this to the path and file name of the desired file. The path entered is relative to the project directory, not absolute.

Recognized Tags

I have classified the XML comment tags into two categories. The first set of tags, which I’ll call primary tags, always starts a group of XML comment tags. They are never embedded within other tags. The second set contains tags that are used within primary tags as modifiers to the text. I call them support tags.

here are nine primary tags: <remarks>, <summary>, <example>, <exception>, <param>, <permission>, <returns>, <seealso>, and <include>.

      In this context, the <remarks> tag is used to describe a type such as a class:

/// <remarks>
/// Class that contains functions to do
/// transformations to help files.
/// </remarks>

The C# documentation recommends using <remarks> to describe a type and a <summary> tag to describe a type member.Oddly, if you start a comment before a type using the /// combination, the Visual Studio .NET IDE will still insert a <summary> tag. Therefore, <remarks> tags need to be inserted manually.

The <summary> tag is the tag found most often in a C# source file. This tag is used to describe type members, including methods, properties, and fields:

/// <summary>
/// This XmlDocument based attribute contains the
/// XML documentation for the project.
/// </summary>

The <summary> tag can describe types as well, but it is not recommended. The XML comment documentation recommends that the <remarks> tag be used for describing types.

The <example> tag is used to mark the beginning of an example showing how to use the item. The example can be any valid text, but most often it is a snippet of code:

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

If code is used, it is usually marked with a <code> tag. The <code> tag will be discussed in the section on support tags.

The <exception> tag documents the exceptions, if any, that the item may throw. If more than one exception may be thrown, then more than one of these tags may be used. Unlike most of the tags, the <exception> tag has one attribute, cref. The value of this attribute is the name of the exception that could be thrown. This must be a valid class because the C# parser will verify it and extract the context information to put into the XML documentation. I will explain this later.

I did not throw any exceptions in the code for this article, but here is an example of how the cref attribute can be used with the <exception> tag:

/// <exception cref="SampleException">
/// Normally, a discussion on any exceptions thrown would go here.
/// </exception>

The <param> tag describes the parameters of a method or property. It is automatically inserted by the IDE when using the three forward slashes before a method. The <param> tag has one attribute, name, which is simply the same name that the parameter has in the source:

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

Member access is identified with the <permission> tag. The text that is assigned to it sets permission-related descriptions. There is no requirement for the value for this tag. Permission is one possibility, with values such as public, private, protected, and so on. Scope is another possible value, with information about whether the method is static. However, you are free to put whatever value you must have here.

The <permission> tag has one attribute—cref. The documentation describes the use of cref in this context as "a reference to a member or field that is available to be called from the current compilation environment." It is usually set to System.Security.PermissionSet:

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

The <returns> tag is similar to the <param> tag, but it’s used to describe what the method or property returns:

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

The <seealso> tag specifies "other" links related to the same topic. This tag usually does not include a text value, just a cref attribute that specifies a reference to a symbol. This could be a type, member, field, and so on.

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

The XML compiler will identify the content of the symbol and use it accordingly in the compiled XML documentation. I’ll discuss this again in the section on the XML documentation file.

When XML comments are extracted from the code by the compiler, any file specified in the <include> tag will be expanded and the comments inside it will be used as if that had been included inline. Because the compiler finds them, you can keep comments in an external file. This can help organize your code, but then the comments are not readily available. I would never use the <include> tag for this reason, but if your comments are lengthy, you may find the trade-off acceptable.

      Several attributes must accompany the <include> tag to specify the external file. The file attribute is the name of the file using relative or fully qualified paths. The include file itself is an XML document that holds XML comments. The path attribute is an XPath statement that points to the parent element of the XML comments in the external document, as you can see here:

/// <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;
   }
}

Support Tags

      There are eleven support tags: <c>, <code>, <list>, <listheader>, <item>, <term>, <description>, <para>, <paramref>, <see>, and <value>.

      The <c> tag marks a line of text as code. It is usually used inline in descriptive text.

/// The source XML is loaded into the <see cref="SourceXML"/>
/// property (e.g. <c><I>obj</I>.SourceXML =
/// "<I>XML goes here</I>"</c>).

The <code> tag also defines a section of text as code. It is often used within an <example> tag block (as shown earlier). The <code> tag is similar to the <c> tag, but <c> is used for a single line of code while <code> is used for a block of code. It specifies that the formatting of the text in the comments needs to remain the same:

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

The <list> tag is used in other comment tags to define a specialized list. The type of list is defined by the type attribute, which can have the values bullet, number, or table. Within the <list> tag, there are tags that denote the components of the list, as you can see in this example:

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

The <listheader> tag holds header information for the list (see the previous example). It is typically used for a table of list types.

As you probably guessed, the <item> tag identifies each item in the list. It can stand alone or wrap <term> and <description> tags. The <term> and <description> tags are always children tags of the <listheader> tag or <item> tags. They are always used in pairs and their function is obvious.

The <para> tag is used to identify a new paragraph. It is very similar to the <P> tag in HTML. You should definitely use this tag to break up long comment sections:

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

If text within a comment needs to have a parameter specially identified, then <paramref> is the tag to use. It is inserted in the text in the location where the parameter text should appear. The main purpose of this tag is to identify the name of a parameter that should be formatted in a special way. It has one attribute, name, which is the name of the parameter that would appear in the text, usually formatted in a special way:

/// Loads the XML documentation in the file specified by
/// <paramref>strFilePath</paramref>.

The <see> tag is used within the text of other comment tags to specify a hyperlink. It is used inline as part of the text and usually just includes one attribute, 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.

The cref attribute specifies a reference to an existing symbol. See the description for the <exception> tag for more information.

The <value> tag defines the meaning of a property member. It is used just like the <remarks> tag is used for classes and the <summary> tag is used for other members.

/// <value>
/// The SourceXML property contains the XML that will be used in
/// the transformations by the member functions for this class.
/// </value>

Generating Documentation

Now that you have successfully created an XML file from the comments you need to generate documentation from it. For this purpose you can download and use nDoc.

Once you have downloaded nDoc, you can use its GUI interface to select a binary from your project directory (make sure it is in the debug folder and the .XML is located next to it).

nDoc allows you to create different types of documentations from simple HTML to MSDN style.

If you need anymore help, please feel free to ask.

Related Article;

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

Share on Facebook