C# XML Documentation Example

The following uses both the multiline and the single-line XML comment. As a point of interest, many programmers use a series of single-line XML comments rather than a multiline comment even when a comment spans several lines. (Several of the comments in this example use this approach.) The advantage is that it clearly identifies each line in a longer XML comment as being part of an XML comment. This is, of course, a stylistic issue, but it is common practice.

// An XML documentation example.

using System;

/** <remarks>
 This is an example of multiline XML documentation.
 The Test class demonstrates several tags.
</remarks>
*/

class Test {
  /// <summary>
  /// Main is where execution begins.
  /// </summary>
  public static void Main() {
    int sum;
    sum = Summation(5);
      Console.WriteLine("Summation of " + 5 + " is " + sum);
  }

  /// <summary>
  /// Summation returns the summation of its argument.
  /// <param name = "val">
  /// The value to be summed is passed in val.
  /// </param>
  /// <see cref="int"> </see>
  /// <returns>
  /// The summation is returned as an int value.
  /// </returns>
  /// </summary>
  static int Summation(int val) {
    int result = 0;

    for(int i=1; i <= val; i++)
      result += i;

    return result;
  }
}

Assuming the preceding program is called XmlTest.cs, the following line will compile the program and produce a file called XmlTest.xml that contains the comments:

csc XmlTest.cs /doc:XmlTest.xml

After compiling, the following XML file is produced:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>XmlTest</name>
    </assembly>
    <members>
        <member name="T:Test">
            <remarks>
             This is an example of multiline XML documentation.
             The Test class demonstrates several tags.
            </remarks>
        </member>
        <member name="M:Test.Main">
            <summary>
            Main is where execution begins.
            </summary>
        </member>
        <member name="M:Test.Summation(System.Int32)">
            <summary>
            Summation returns the summation of its argument.
            <param name="val">
            The value to be summed is passed in val.
            </param>
            <see cref="T:System.Int32"> </see>
            <returns>
            The summation is returned as an int value.
            </returns>
            </summary>
        </member>
    </members>
</doc>

Notice that each documented element is given a unique identifier. These identifiers can be used by other programs that use the XML documentation.