C# 4 and .NET 4

54 ❘ ChaPTer 2 cOre c#
(continued)
Tag
desCriPTion
Adds a description for a member.
Documents the return value for a method.
Provides a cross-reference to another parameter. (Syntax is verified by the compiler.)
Provides a “see also” section in a description. (Syntax is verified by the compiler.)
Provides a short summary of a type or member.
Describes a property.
To see how this works, add some XML comments to the MathLibrary.cs file from the previous “More on
Compiling C# Files” section. You will add a element for the class and for its Add() method, and
also a element and two elements for the Add() method:
// MathLib.cs
namespace Wrox
{
}
///
/// Wrox.Math class.
/// Provides a method to add two integers.
///
public class MathLib
{
///
/// The Add method allows us to add two integers.
///
///Result of the addition (int)
///First number to add
///Second number to add
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:MathLibrary.xml MathLibrary.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:
MathLibrary
Wrox.MathLibrary class.
Provides a method to add two integers.
www.it-ebooks.info