Programming C#

XML Documentation Comments

C# supports a new Documentation Comment style, with three slash marks (///). You can see these comments sprinkled throughout Example 13-3. The Visual Studio.NET editor recognizes these comments and helps format them properly.

The C# compiler processes these comments into an XML file. You can create this file by using the /doc command-line switch. For example, you might compile the program in Example 13-3 with this command line:

csc filecopier.cs /r:System.Windows.Forms.dll /r:mscorlib.dll 
/r:system.dll /r:system.configuration.dll /r:system.data.dll 
/r:system.diagnostics.dll /r:system.drawing.dll /r:microsoft.win32.interop.dll 
/doc:XMLDoc.XML

You can accomplish this same operation in Visual Studio .NET by clicking a project icon in the Solution Explorer window, selecting View → Property Pages on the Visual Studio menu, and then clicking the Configuration Properties folder. Within the Configuration Properties folder, click the Build property page and type in a name for the XML Documentation File property to specify a name for the XML file you want to produce.

Either approach produces the file XMLDoc.XML with your comments in XML format. An excerpt of the file that will be produced for the FileCopier application of the previous section is shown in Example 13-4.

Example 13-4. The XML output (excerpt) for file copy

<?xml version="1.0"?> <doc> <assembly> <name>FileCopier</name> </assembly> <members> <member name="T:FileCopier.Form1"> <summary> Form demonstrating ...