C# 2008 Programmer's Reference

change during runtime.

Comments

In C#, you can insert comments into your program using either // or a mirrored pair of /* and */. The following example shows how to insert comments into your program using //:

//---declare the variables---
int num1; //---num1 variable---
int num2 = 5; //---num2 variable---
float num3, num4; //---num3 and num4 variables---

And here's an example of how to insert a multi-line block of comments into your program:

/*
 Declares the following variables: num1, num2, num3, num4
*/
int num1;
int num2 = 5;
float num3, num4;

In general, use the // for short, single-line comments and /* */ for multi- line comments.

XML Documentation

One of the very cool features available in Visual Studio 2008 is the support for XML documentation. This feature enables you to insert comments into your code using XML elements and then generate a separate XML file containing all the documentation. You can then convert the XML file into professional- looking documentation for your code. 

To insert an XML comment into your code, position the cursor before a class or method name and type three / characters (left window in Figure 3-6). The XML template is automatically inserted for you (see the right window in Figure 3-6).

Figure 3-6 

The following code shows the XML documentation template created for the Program class, the Main() method, and the AddNumbers() method (you need to fill in the description for each element):

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace HelloWorld {
 /// <summary>
 /// This is my first C# program.
 /// </summary>
 class Program {
  /// <summary>
  /// The entry point for the program
  /// </summary>
  /// <param name='args'<Argument(s) from the command line</param>
  static void Main(string[] args) {
   Console.Write('Hello, ');
   for (int i = 0; i < args.Length; i++)
    Console.Write('{0} ', args[i]);
   Console.Write('! This is my first C# program!');
   Console.ReadLine();
   return;
  }
  /// <summary>
  /// Adds two numbers and returns the result
  /// </summary>
  /// <param name='num1'>Number 1</param>
  /// <param name='num2'>Number 2</param>
  /// <returns> Sum of Number 1 and 2</returns>
  private int AddNumbers(int num1, int num2) {
   //---implementations here---
  }
 }
}

To enable generation of the XML document containing the XML comments, right-click the project name in Solution Explorer and select Properties.

You can also generate the XML documentation file using the csc.exe compiler at the command prompt using the /doc option:

csc Program.cs /doc:HelloWorld.xml

In the Build tab, tick the XML Documentation File checkbox and use the default path suggested: binDebugHelloWorld.XML (see Figure 3-7).

Figure 3-7

Build the project by right-clicking the project name in Solution Explorer and selecting Build.

You will now find the HelloWorld.xml file (see Figure 3-8) located in the binDebug folder of the project.

Figure 3-8

You can now convert this XML file into a MSDN-style documentation file. Appendix C shows you how to use the SandCastle tool to do this.

Data Types