Most developers will use only <summary>, <remarks>, <param>, and <returns> because those are the only tags used by the Code Comment Report. Using any of the other tags would require creating an XSLT file to process them. While this is a great feature, most developers will not have time for this. The sample that we will work through below will concentrate on the basic tags and show how to use them in IntelliSense and the Code Comment Report.

Create the Class Library
In this example we will create a C# class library that will be used by other developers. In VS.NET, create a C# class library project called CommentsLibrary and enter or paste the undocumented code shown in Listing 1 into the class file that is created. Now position your cursor above the class declaration and type "///". You should see that the IDE automatically inserts the <summary> and </summary> tag. This is curious since the C# documentation recommends using the <remarks> tag for types, but we want to use <summary> so that IntelliSense will pick it up. Type or paste the corresponding comment from Listing 2. Now position your cursor above the definition of the UserName property and type "///", and again you should see that it provides the <summary> tags for you.

After putting the UserName comment in, position your cursor over the AddTwoNumbers function and type "///". Not only will the IDE again provide the <summary> tags for you, since you are now documenting a function, it also inserts two <param> tags for your parameters and a <return> tag! Doing the same thing above the SubtractTwoNumbers routine will provide the same result, except the <return> tag is not provided because SubtractTwoNumbers is not a function. What a great help this functionality is to busy developers who want to document their code. To me, this is one of the biggest advantages that C# holds over VB.NET, which does not provide this functionality. On large projects, having this kind of documentation available is invaluable.

Now that we have fully documented our class library, it should look similar to Listing 2. We are almost ready to build the assembly, but first we have to tell VS.NET to create the XML Documentation file. Go to the Solution Explorer, right-click on the project, and select Properties. In the resulting dialog box, select Build under the Configuration Properties folder. Near the bottom, you will see an "XML Documentation File" property. Enter the name of the XML file to be generated. The name must match the DLL name or IntelliSense will not find it. In this case, we will name the file CommentsLibrary.xml.

Now build the project to generate the DLL file in the bin/Debug folder. Notice that a CommentsLibrary.xml file has also been created. The contents of this file are shown in Listing 3.

Test the Component in Another Project
Now return to VS.NET and close the CommentsLibrary project and add a new C# Class library project, called Tester. Add CommentsLibrary .dll as a reference. Add the following using statement to the class file:

using CommentsLibrary;

Now, go into the constructor that was created automatically and start typing the following "DummyClass dm = new Du". Once you get past the new keyword, IntelliSense will drop down and should find DummyClass in the dropdown list, as shown in Figure 1.

Notice that you see the summary text for the DummyClass type. Complete that line and move to the next line. Now type "cl.User" and IntelliSense will highlight the UserName property. Drag your mouse over UserName and you will see the summary you entered for that property. Erase that line and type "int i = cl.Add", and drag your mouse over the AddTwoNumbers function, as shown in Figure 2.

Double-click AddTwoNumbers, then type a left parenthesis, and IntelliSense will show you the parameters seen in Figure 3.

Try it again for the SubtractTwoNumbers routine and you'll see the same thing. If you have done any .NET programming at all, this should look very familiar to you. And if you're like me, you depend heavily on IntelliSense to make your job easier, so it is exciting (at least to me) to see that you can provide the same functionality to other programmers!

Create a Code Comment Report
Now let's look at another way to provide documentation from our XML comments. VS.NET has a utility that uses the XML comments in your project to create help files in the form of HTML pages. It's called a Code Comment Report. Return to the CommentsLibrary project, and click on Tools/Build Comment Web Pages. You can generate reports for an entire solution or just for specific projects. Then you choose a folder to contain the files, and click OK. VS.NET will generate pages that are formatted in a similar fashion to MSDN's help pages. You can then create a virtual directory in IIS, point it to the folder that contains the pages, and publish these pages for other developers to browse as they develop with your component.

Extending Functionality
The Code Comment report is a canned report, and is certainly not perfect. Since the XML comments are generated into an XML file (shown in Listing 3), developers are free to use any XML formatting tool they like to generate help files. The most obvious choice is to apply XSLT to the XML files to create custom HTML help pages. This would yield the greatest benefit to very large projects or commercial applications that need to provide help files for exposed components.

Conclusion
XML documentation is a giant leap forward for documenting your code. Used properly, you can quickly and easily provide first-class help files and IntelliSense tips. This ability will greatly improve the shareability of your components.

About The Author
James Horan is an independent consultant in the Philadelphia area. He is currently using Microsoft .NET technology to provide solutions for manufacturing clients. He also runs www.dotnetgenius.com. horan@jwtechnology.com

	



Listing 1: Undocumented class library

using System;
namespace CommentsLibrary
{
    public class DummyClass
    {
        public string UserName;

        public int AddTwoNumbers(int a, int b)
        {
            return a+b;
        }

        public void SubtractTwoNumbers(int a, int b)
        {
            result = a-b;
        }

    }
}


Listing 2: Documented class library


using System;
namespace CommentsLibrary
{
 /// <summary>
 /// This class is strictly used for demonstrat
 /// ing XML comments.
 /// </summary>
 /// public class DummyClass
        {
 /// <summary>
 /// String field containing the User's name.
 /// </summary>
 ///         public string UserName;

 /// <summary>
 /// This method adds two numbers and returns
 /// the result.
 /// </summary>
 /// <param name="a">
 /// The first number to be added.
 /// </param>
 /// <param name="b">
 /// The second number to be added.
 /// </param>
 /// <returns>
 /// An integer that is the result of the addi
 /// tion.
 /// </returns>
 ///         public int AddTwoNumbers(int a, int b)
        {
            return a+b;
        }

 /// <summary>
 /// This method subtracts two numbers and
 /// returns the
 /// result.
 /// </summary>
 /// <param name="a">
 /// The first number to be subtracted.
 /// </param>
 /// <param name="b">
 /// The second number to be sub
 /// tracted.
 /// </param>
 /// <param name="result">
 /// The result of the subtraction.
 /// </param>
 /// public void SubtractTwoNumbers(int a, int b)
        {
            result = a-b;
        }

    }
}


Listing 3: Generated comments XML File.


<?xml version="1.0"?>
<doc>
    <assembly>
        <name>CommentsLibrary</name>
    </assembly>
    <members>
        <member name="T:CommentsLibrary.
                         DummyClass">
            <summary>
     This class is strictly used for demonstrating XML comments.
            </summary>
        </member>
        <member name="F:Comments
                        Library.DummyClass.UserName">
            <summary>
            String field containing the User's name.
            </summary>
        </member>
        <member name="M:CommentsLibrary.DummyClass.
                      AddTwoNumbers(System.Int32,System.Int32)">
            <summary>
            This method adds two numbers and
             returns the result.
            </summary>
            <param name="a">The first number to
            be added.</param>
            <param name="b">The second number to
            be added.</param>
            <returns>An integer that is the
            result of the addition</returns>
        </member>
        <member name="M:CommentsLibrary.DummyClass.
        SubtractTwoNumbers(System.Int32,
        System.Int32,System.Int32)">
            <summary>
            This method subtracts two numbers and
            returns the result.
            </summary>
            <param name="a">The first number to
            be subtracted.</param>
            <param name="b">The second number to
            be subtracted.</param>
            <param name="result">The result of
            the subtraction.</param>
        </member>
    </members>
</doc>