Internal Comments within the Source Files

As noted earlier in this chapter, C# uses the traditional C-type single-line (// ...) and multiline (/* ... */) comments:

// This is a single-line comment
/* This comment
   spans multiple lines. */

Everything in a single-line comment, from the // to the end of the line, will be ignored by the compiler, and everything from an opening /* to the next */ in a multiline comment combination will be ignored. Obviously, you can’t include the combination */ in any multiline comments, because this will be treated as the end of the comment.

It is actually possible to put multiline comments within a line of code:

Console.WriteLine(/* Here's a comment! */ "This will compile.");

Inline comments like this should be used with care because they can make code hard to read. However, they can be useful when debugging if, say, you temporarily want to try running the code with a different value somewhere:

DoSomething(Width, /*Height*/ 100);

Comment characters included in string literals are, of course, treated like normal characters:

string s = "/* This is just a normal string .*/";

XML Documentation

In addition to the C-type comments, illustrated in the preceding section, C# has a very neat feature that we can’t omit from this chapter: the ability to produce documentation in XML format automatically from special comments. These comments are single-line comments but begin with three slashes (///), instead of the usual two. Within these comments, you can place XML tags containing documentation of the types and type members in your code.

The tags in the following table are recognized by the compiler.

Open table as spreadsheet

Tag	Description
<c>	Marks up text within a line as code, for example: <c>int i = 10;</c>
<code>	Marks multiple lines as code.
<example>	Marks up a code example.
<exception>	Documents an exception class. (Syntax is verified by the compiler.)
<include>	Includes comments from another documentation file. (Syntax is verified by the compiler.)
<list>	Inserts a list into the documentation.
<param>	Marks up a method parameter. (Syntax is verified by the compiler.)
<paramref>	Indicates that a word is a method parameter. (Syntax is verified by the compiler.)
<permission>	Documents access to a member. (Syntax is verified by the compiler.)
<remarks>	Adds a description for a member.
<returns>	Documents the return value for a method.
<see>	Provides a cross-reference to another parameter. (Syntax is verified by the compiler.)
<seealso>	Provides a “see also” section in a description. (Syntax is verified by the compiler.)
<summary>	Provides a short summary of a type or member.
<value>	Describes a property.

To see how this works, add some XML comments to the MathLibrary.cs file from the “More on Compiling C# Files” section, and call it Math.cs. You will add a <summary> element for the class and for its Add() method, and also a <returns> element and two <param> elements for the Add() method:

// Math.cs
namespace Wrox.ProCSharp.Basics
{

   ///<summary>
   ///   Wrox.ProCSharp.Basics.Math class.
   ///   Provides a method to add two integers.
   ///</summary>
   public class Math
   {
      ///<summary>
      ///   The Add method allows us to add two integers.
      ///</summary>
      ///<returns>Result of the addition (int)</returns>
      ///<param name="x">First number to add</param>
      ///<param name="y">Second number to add</param>
      public int Add(int x, int y)
      {
         return x + y;
      }
   }
}

The C# compiler can extract the XML elements from the special comments and use them to generate an XML file. To get the compiler to generate the XML documentation for an assembly, you specify the /doc option when you compile, together with the name of the file you want to be created:

csc /t:library /doc:Math.xml Math.cs

The compiler will throw an error if the XML comments do not result in a well-formed XML document.

This will generate an XML file named Math.xml, which looks like this:

<?xml version="1.0"?>
<doc>
   <assembly>
      <name>Math</name>
   </assembly>
   <members>
      <member name="T:Wrox.ProCSharp.Basics.Math">
         <summary>
            Wrox.ProCSharp.Basics.Math class.
            Provides a method to add two integers.
         </summary>
      </member>
      <member name=
            "M:Wrox.ProCSharp.Basics.Math.Add(System.Int32,System.Int32)">
         <summary>
            The Add method allows us to add two integers.
         </summary>
         <returns>Result of the addition (int)</returns>
         <param name="x">First number to add</param>
         <param name="y">Second number to add</param>
      </member>
   </members>
</doc>

Notice how the compiler has actually done some work for you; it has created an <assembly> element and also added a <member> element for each type or member of a type in the file. Each <member> element has a name attribute with the full name of the member as its value, prefixed by a letter that indicates whether this is a type (T:), field (F:), or member (M:).