HomeDigital EditionSearch Dotnet Cd
ASP.NET C# Certification Exams The CLI Data Access Editorials Extending .NET Fundamentals Interoperability Interviews Migrate Mobile .NET Mono .NET Interface Object-Oriented Programming Open Source Optimization Product/Book Reviews Security Source Code UML Visual Studio .NET

Frequently, documentation gets lip service and not much else. Everyone who develops software will tell you how important good code commenting is to the maintainability of applications. But in the same breath they will tell you that they are rarely given the time to properly document their code. To assist the developer in this pursuit, the designers of C# and Visual Studio .NET have provided XML documentation. XML comments allow developers to enter information about their code once, then be able to provide others with this information in several different ways. These methods include:
1.   IntelliSense documentation
2.   Visual Studio .NET Code Comment Reports (automated documentation reports)
3.   Custom documentation files using XSL.

XML Comments
XML comments are identified to the compiler with three forward slashes (///). Developers use two forward slashes (//) for regular comments; the third slash tells the parser that a comment is an XML comment and should be handled as such.

IntelliSense Tags
IntelliSense is the best thing out of Microsoft since sliced bread (wait, they didn't develop sliced bread?). It greatly reduces development time by providing a developer with inline documentation that provides information on the proper syntax for creating objects, calling methods, or accessing properties. XML comments allow you to provide IntelliSense support for your components and applications. So let's start with the XML comment tags that IntelliSense supports.

The <summary> tag is used to describe types (classes) and type members (methods, properties, and fields). C# documentation recommends using the <remarks> tag for types, but information contained inside <remarks> tags will not show up in IntelliSense. So if you want IntelliSense to describe your type, you must use the <summary> tag. Here is an example:

/// <summary>
/// This method adds two numbers
/// and returns the result.
/// </summary>
The only other tag that IntelliSense recognizes is the <param> tag, which is used to describe each parameter in a method:

/// <param name="a">The first num
/// ber to be added.</param>
/// <param name="b">The second
/// number to be added.</param>

Code Comment Report Tags
As mentioned previously, VS.NET provides a utility that will generate HTML files containing information from your XML comments. This utility uses the <summary>, <remarks>, and <param> tags, as well as two others. Most important, it uses the <returns> tag, which specifies what is returned from a function:

/// <returns>
/// An integer that represents the
/// result of the addition.
/// </returns>

It also uses the <newpara> tag, which allows a new paragraph to be inserted in the comments, but this tag is rarely used.

Other Tags
Here is a listing of the rest of the tags used in XML comments:

  • <example>: Used to provide code examples and descriptive text for examples.
  • <code>, <c>: Used to specify code within comments. The <code> tag is normally used within the <example> tag to specify a block of code. The <c> tag is normally used to provide one line of code inside comments.
  • <exception>: Used to provide information on exceptions that could be thrown by a method. This tag has an attribute, called cref, whose value is the name of the exception that could be thrown. This name must be a valid class; the C# parser will extract the context information and include it in the documentation.
  • <permission>: Defines member access to the type or type member.
  • <seealso>: Used to provide links related to the current topic. This tag usually does not have a value, just a cref attribute that specifies a reference to a symbol (a type, method, property, etc.).
  • <include>: Used to allow other XML documentation files to be included in the current file. This tag has a name attribute for the name of the file, and a path attribute for the fully qualified path to the file.
  • <list>: Used to define a specialized list. This tag has a type attribute to define the list as numbered, bulleted, or tabled.
  • <listheader>: Used to hold header information for a <list>.
  • <item>: Used to hold items in a <list>.
  • <term>: Used within <listheader> or <item>.
  • <description>: Used within <listheader> or <item>.

    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.

    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.

    Figure 2

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

    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. [email protected]

    	
    
    
    
    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>
    

    All Rights Reserved
    Copyright ©  2004 SYS-CON Media, Inc.

      E-mail: [email protected]