Title: Use XML comments in C#

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.

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.

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.

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 the example to experiment with it and to see additional details.