Книга: C# 2008 Programmer

XML Documentation

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.

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.

Оглавление книги