An XML Documentation Example

Here is an example that demonstrates several XML comments. It 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.