Use XML comments in C#

[XML comments]

C# let’s you use XML comments to give extra information to IntelliSense and that can be used to automatically generate documentation. These comments start with three / symbols and should be placed before the program item to which they apply. That item can be such things as a class declaration, a property or method within a class, or a variable declared within a class.

Within XML comments, XML-style tags tell Visual Studio what the information you type represents. For example, the <summary> tag indicates that the included text is a summary describing the code item that follows.

If you build the code item’s declaration and then type /// on the line before it, Visual Studio inserts a template for XML comments. For example, consider the following code. Here I defined a constructor for the TestScore class and then typed /// on the line before it. Visual Studio added the rest including the <summary> and <param> tags.

/// <summary>
/// 
/// </summary>
/// <param name="test_number"></param>
/// <param name="score"></param>
public TestScore(int test_number, int score)
{
}

If you have the method’s signature defined, including any parameters, then Visual Studio can add <param> tags for them. If you need to add parameters later, you can simply add a new <param> tag yourself.

Now you can fill in the information you want IntelliSense to provide for the different parts of the XML comments. The following code shows the XML comments I added for this constructor.

/// <summary>
/// Constructor that initializes a specific test score.
/// </summary>
/// <param name="test_number">The test number.</param>
/// <param name="score">The student's score between 0 and 100.</param>
public TestScore(int test_number, int score)
{
}

The following code shows the XML comments I added for the TestScore class.

/// <summary>
/// Represents a test score for a student on a particular test.
/// </summary>
class TestScore
{
}

To see how this helps with IntelliSense, look at the following picture.


[XML comments]

Here I typed part of the class name TestScore. IntelliSense lists the TestScore class as one of its possible matches and displays the information I entered in the class’s <summary> tag.

Now consider the following figure.


[XML comments]

Here I finished typing the class’s name and typed the open parenthesis. IntelliSense now shows a message giving the information I put in the XML comments for the constructor’s first <param> tag. After you enter that parameter’s value and a comma, IntelliSense shows the XML comments for the second <param> tag. If there were other parameters or other overloaded constructors, IntelliSense would display information taken from other tags when appropriate. Download the example and experiment with the code in the code editor to see how the XML comments give IntelliSense information to display.

In addition to helping IntelliSense, XML comments let Visual Studio automatically generate documentation for your code. To enable that documentation, open the Project menu and select Properties. On the property page’s Build tab, scroll to the bottom and check the XML Documentation File box as shown in the following picture.


[XML comments]

Change the path where the XML documentation will be stored if you like and then save.

Now when you build the program, Visual Studio extracts the XML comments and builds an XML documentation file. You can reformat that file or pull data out of it to build your own documentation.

Visual Studio will also warn you if it finds public code items that do not have XML comments.

The following code shows the XML document generated for the example program.

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>howto_xml_comments</name>
    </assembly>
    <members>
        <member name="M:howto_xml_comments.Program.Main">
            <summary>
            The main entry point for the application.
            </summary>
        </member>
        <member name="T:howto_xml_comments.Form1">
            <summary>
            The test program's main form.
            </summary>
        </member>
        <member name="F:howto_xml_comments.Form1.components">
            <summary>
            Required designer variable.
            </summary>
        </member>
        <member name="M:howto_xml_comments.Form1.Dispose(System.Boolean)">
            <summary>
            Clean up any resources being used.
            </summary>
            <param name="disposing">true if managed resources should be disposed; otherwise, false.</param>
        </member>
        <member name="M:howto_xml_comments.Form1.InitializeComponent">
            <summary>
            Required method for Designer support - do not modify
            the contents of this method with the code editor.
            </summary>
        </member>
        <member name="M:howto_xml_comments.Form1.#ctor">
            <summary>
            Initialize the form. (Because this is automatically generated code
            you might think it would automatically generate the XML comment
            but it doesn't.)
            </summary>
        </member>
        <member name="T:howto_xml_comments.Properties.Resources">
            <summary>
              A strongly-typed resource class, for looking up localized strings, etc.
            </summary>
        </member>
        <member name="P:howto_xml_comments.Properties.Resources.ResourceManager">
            <summary>
              Returns the cached ResourceManager instance used by this class.
            </summary>
        </member>
        <member name="P:howto_xml_comments.Properties.Resources.Culture">
            <summary>
              Overrides the current thread's CurrentUICulture property for all
              resource lookups using this strongly typed resource class.
            </summary>
        </member>
        <member name="T:howto_xml_comments.TestScore">
            <summary>
            Represents a test score for a student on a particular test.
            </summary>
        </member>
        <member name="F:howto_xml_comments.TestScore._TestNumber">
            <summary>
            This test's identifying number.
            </summary>
        </member>
        <member name="F:howto_xml_comments.TestScore._Score">
            <summary>
            This score the student got on this test.
            </summary>
        </member>
        <member name="M:howto_xml_comments.TestScore.#ctor(System.Int32,System.Int32)">
            <summary>
            Constructor that initializes a specific test score.
            </summary>
            <param name="test_number">The test number.</param>
            <param name="score">The student's score between 0 and 100.</param>
        </member>
        <member name="M:howto_xml_comments.TestScore.Grade(System.Int32[],System.String[])">
            <summary>
            Return the letter grade for this test.
            </summary>
            <param name="grade_breaks">Break points for letter grades A, B, C, D, and F.
            For example, if score >= grade_breaks[0] then the score is A.</param>
            <param name="grade_names">The name of the grade for the corresponding break point.</param>
            <returns>The letter grade for this test.</returns>
        </member>
    </members>
</doc>

Adding XML comments is a bit of extra work, but it makes code easier to write and provides some minimal level of documentation.


Download Example   Follow me on Twitter   RSS feed   Donate




This entry was posted in debugging, syntax, tips and tagged , , , , , , , , , , . Bookmark the permalink.

2 Responses to Use XML comments in C#

  1. David says:

    Is there a way to have the summary show above the param listing?

    So, in your example, the first line would display, ” Constructor that initializes a specific test score.”, and the param entry would be on a new line below.

  2. Rod Stephens says:

    Do you mean when IntelliSense is showing the parameters as you type them? As far as I know, you can’t change the way IntelliSense displays the information. It displays the summary when you hover over a method and it displays the information about each parameter when you’re typing that parameter.

    You could repeat the summary before each parameter’s description, but I haven’t found a way to add a new line.

    Or are you talking about in the XML documentation? The idea there is to generate it as it is shown and then use XSLT or some other method to reformat it to your liking.

    Let me know if neither of those was what you meant.

Leave a Reply

Your email address will not be published. Required fields are marked *