Using Comments

 

Chapter 2 - C# Basics
bySimon Robinsonet al.
Wrox Press 2002

  

The last topic we will look at in this chapter looks very simple on the surface - adding comments to our code. As we noted at the start of the previous chapter, C# uses the traditional C-type single-line ( // ... ) and multi-line ( /* ... */ ) 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 multi-line comment combination will be ignored. Obviously we can't include the combination */ in any multi-line comments, as this will be treated as the end of the comment.

It is actually possible (although definitely not recommended) to put multi-line comments within a line of code:

   Console.WriteLine(/* Please don't do this! */ "This will compile");   

Although having said that, inline comments like this 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 above, C# has a very neat feature that we can't leave this chapter without discussing: 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, we can place XML tags containing documentation of the types and type members in our code.

The following tags are recognized by the compiler:

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 verified by the compiler.)
< include >	Includes comments from another documentation file. (Syntax verified by the compiler.)
< list >	Inserts a list into the documentation.
< param >	Marks up a method parameter. (Syntax verified by the compiler.)
< paramref >	Indicates that a word is a method parameter. (Syntax verified by the compiler.)
< permission >	Documents access to a member. (Syntax 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 verified by the compiler.)
< seealso >	Provides a 'see also' section in a description. (Syntax verified by the compiler.)
< summary >	Provides a short summary of a type or member.
< value >	Describes a property.

To see how this works, let's add some XML comments to the MathLibrary.cs file from an earlier section, and call it Math.cs . We 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, we specify the /doc option when we compile, together with the name of the file we want to be created:

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

Important 

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 us; 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: ).

XML Documentation in Visual Studio .NET

We don't want to concentrate too much on Visual Studio .NET this early in the book, as most of the functionality it provides is quite straightforward. However, it is worth mentioning in this context that if you're using Visual Studio .NET, it can save you quite a lot of typing when compiling XML documentation.

Open up the Math.cs file in Visual Studio .NET, and add a blank line before the definition of the Add() method. Now, type three forward slashes ( /// ) at the start of the line. Visual Studio very kindly adds a whole lot of XML tags for us:

All we have to do is type in the actual descriptions. Notice how Visual Studio .NET has even managed to put in the correct values for the parameter names in the < param > tags.

In order to generate the XML documentation when the project is compiled, specify an XML Documentation File on the Build menu under Configuration Properties on the project's property pages.

Visual Studio .NET can also generate HTML-formatted documentation from these XML comments. To do this, select Tools Build Comment Web Pages... from the menu. We are now asked whether we want to generate XML documentation for the entire solution, or just for selected projects. We are also asked where we want to save the generated HTML pages. When we select OK , Visual Studio .NET will generate a whole set of HTML pages documenting our project, which we can browse through Visual Studio .NET or any web browser: