Professional.Open.Source.dot.NET.Development.Programming.with.NAnt.NUnit.NDoc [Electronic resources] نسخه متنی

C# XML Documentation

Deep within the C# compiler is a parser with the great built-in feature of XML documentation. Using the combination of a specialized comment construct of three slashes (///) and built-in documentation tags, XML documentation can be created. The compiler ignores the comments because of the first two slashes, which are standard single-line commenting, and the C# parser looks for the third slash to signify documentation. While the tags used in XML documentation are configurable, the C# standard has predefined a set of tags. The standard tag set has special meanings for the C# compiler, but you can create your own tags to enforce standard documentation and consistent formatting options for your project. The C# compiler only requires that XML comments be well formed. The predefined documentation tags can be subdivided in a couple of different ways. First, I will categorize the tags into two categories: Validated and Nonvalidated.

Validated Tags

The C# compiler validates the syntax of these tags. This is to ensure that the documentation matches the code. Table 5.1 shows the documentation tags that are verified by the C# compiler.

If the syntax of these tags is not correct, then you will receive a compiler level 1 warning. Table 5.2 lists the XML documentation compiler warnings.

These warnings can be ignored by setting a high threshold for warnings or by ignoring a specific error number. The main reason that these tags are validated is that the resulting XML file is used for VS.NET's and Sharpdevelop's intellisense autocomplete. When an assembly reference is added to a project, both the DLL and the XML file are copied to the output directory of the application. IntelliSense will now parse the XML file and give the appropriate ToolTips.

NOTE

The XML Documentation files for Microsoft's .NET CLR Implementation can be found in [WindowsDir]\Microsoft.NET\Framework\vx.x.xxxx\*.xml for each version of the framework SDK that is installed.

Nonvalidated Tags

The documentation tags listed in Table 5.3 are not validated by the compiler. Mostly, these tags are for documentation purposes only.

These nonvalidated tags are simply passed through the compiler just as a custom tag would be. Therefore, these tags will not cause a warning but are meant mostly for formatting the output to make it more readable.

C# XML Documentation Tag Reference

Another way of categorizing the tags is to group them again into two groups. Each of these tags will be accompanied with a short code example and brief description. The first group is major tags, which always start an XML comment and are never embedded within another set of tags. There are eleven major documentation tags.

Major Documentation Tags

<example>

The example tag is probably the most-used piece of documentation by users. This is the wonderful piece of code that can be cut and pasted from your documentation into the end users' code. Listing 5.1 shows the XML documentation required to create this example code in your documentation.

Listing 5.1. Example XML Documentation Tag

///<example>
/// <code>
///    int result = Add(1, 2);
//  </code>
///</example>
public static int Add(int a, int b)
{
//...
}

<exception>

The exception tag is very important to include with your documentation. Because C# (and most .NET languages, for that matter) does not have a throws keyword like Java, the exception documentation becomes very important. Short of using a decompiler or reflection, there is no easy way of finding out what exceptions a method throws other than the exception documentation tag, as shown in Listing 5.2.

Listing 5.2. Exception XML Documentation Tag

public class DataLib
{
/// <exception cref="System.Data.DataException"></exception>
public static DataSet getCustomers()
{
throw new System.Data.DataException();
// ...
}
}

<include>

In the beginning of the chapter, I mentioned that some developers like to have the documentation with the code to ensure synchronization, but some developers consider well-documented code to be cluttered with XML and find it hard to decipher the code from the comments. This is where the include tag (see Listing 5.3) can help. The include tag allows the C# XML documentation to be in a separate XML file and still be included in the automatic generation of the documentation.

Listing 5.3. Include XML Documentation Tag

/// <include file='xml_documentation_file.xml' path='dev/src/docs' />
public void Test()
{
// ...
}

<param>

The param tag allows you to give the user a little insight into the parameters of a method. Although the code alone should be very readable, this tag can be very useful to a user who may not be thinking along the same lines as the implementer. A good illustration of this is Listing 5.4.

Listing 5.4. Param XML Documentation Tag

/// <param><c>x</c> is a given point</param>
/// <param><c>y</c> is the point to subtract from <c>x</c>.</param>
public void Subtract(Point x, Point y)
{
// ,,,
}

<permission>

Like the exception tag, the permission tag allows you to communicate information to your user that will save him or her valuable time. Again the only way to find out the permissions that a method requires is to use reflection on the Permission Attribute Metadata or to read it in the documentation. Listing 5.5 shows a normal, public method that does not have any special requirements.

Listing 5.5. Permission XML Documentation Tag

/// <permission cref="System.Security.PermissionSet">Anyone can
/// call this method.</permission>
public string HelloWorld()
{
// ...
}

<remarks>

Other than the example tag which gives a user some quick code to cut and paste, the remarks tag will probably be the most read part of your documentation. This is the tag that allows you to describe to your user the purpose of your class, as seen in Listing 5.6.

Listing 5.6. Remarks XML Documentation Tag

/// <remarks>Class <c>Rectangle</c> enables drawing of a
/// rectangle.</remarks>
public class Rectangle
{
// ...
}

<returns>

For publicly available methods, a simple object browser can reveal the return type of the function. However, it is nice for complete documentation to include everything an end user would want, and more importantly, it is very useful when coding with intellisense-enabled IDEs. Listing 5.7 shows the common use of the returns tag.

Listing 5.7. Returns XML Documentation Tag

/// <returns>This method overrides the Equals method of
/// Object and could do a special comparison.  It returns if the
/// Objects are Equal or not.</returns>
public override bool Equals(object o)
{
return base.Equals(o);
}

<seealso>

Listing 5.8 demonstrates the seealso tag to direct users to other useful documentation.

Listing 5.8. Seealso XML Documentation Tag

/// <summary>This method determines whether two Rectangles
/// are the same.</summary>
/// <seealso cref="operator=="/>
/// <seealso cref="operator!="/>
public override bool Equals(object o)
{
// ...
}

<summary>

Similar to the remarks tag, a summary (shown in Listing 5.9) gives useful information to the user about the author's intended functionality. Whereas remarks are used at a class level, the summary tag is used on methods and properties of a class.

Listing 5.9. Summary XML Documentation Tag

/// <summary>Logger is a general class to Log information.</summary>
public Logger()
{
///...
}

Minor Documentation Tag

The second grouping of tags is minor tags. In contrast to the major tags, which stand alone, these tags are descriptive tags that are usually embedded within a major tag. There are eleven minor tags.

<c>

The c tag is used to mark code within a textual description. As you can see in Listing 5.10, the c tag is for simple, single line code. For more verbose code examples, use the code tag.

Listing 5.10. C XML Documentation Tag

/// <param><c>x</c> is a given point</param>
/// <param><c>y</c> is the point to subtract from <c>x</c>.</param>
public void subtract(Point x, Point y)
{
// ,,,
}

<code>

The code tag is usually embedded within an example tag for multiple lines of code. As was already mentioned, most users heavily depend upon this. The major difference between an example and code is that code is a subset of an example, which may contain more information than just code. Listing 5.11 illustrates the code tag.

Listing 5.11. Code XML Documentation Tag

///<example>
/// <code>
///    int result = add(1, 2);
//  </code>
///</example>
public static int add(int a, int b)
{
//...
}

<list>

A list can really improve the look of your documentation. Listing 5.12 shows how to use, in this case, a numbered list.

Listing 5.12. List XML Documentation Tag

/// <list type="number">
/// <item>
/// <description>Never call this function.</description>
/// </item>
/// <item>
/// <description>There is no guarantee of what it will do.</description>
/// </item>
/// </list>
/// </remarks>
public void Test()
{
// ...
}

<para>

Without formatting, documentation would be much harder to read. Imagine this book without chapters or paragraphs. If documentation is hard to read, then users will not use it and in turn will perceive your product as hard to use. The para tag (Listing 5.13) is used to format your documentation by creating paragraph breaks.

Listing 5.13. Para XML Documentation Tag

/// <summary>Log is a general class to Log information.
///  <para> I find general functions like
 this one to be very useful.</para>
///</summary>
public static void Log()
{
// ...
}

<paramref>

The paramref tag in Listing 5.14 is meant as a compliment to the param tag. While the parm tag is used for intellisense and required for robust documentation, the paramref tag is usually found within a summary or remarks tag. This links the user to the parameter, as defined by the param tag.

Listing 5.14. Paramref XML Documentation Tag

/// <summary>This constructor initializes the new Line to
///(<paramref name="a"/>,
/// <paramref name="b"/>).</summary>
public Line(Point a, Point b)
{
// ...
}

<see>

Similar to the seealso tag, the see tag points the readers to more useful documentation. The see tag, however, can be embedded within other tags, as shown in Listing 5.15. Typically, a hyperlink or other method of link is used to allow the users to quickly look at something else; in this case, it's the documentation for the Point class.

Listing 5.15. See XML Documentation Tag

/// <value>Property <c>X</c> represents the Rectangles
/// top left <see cref="Point"/>.</value>
public Point X
{
// ...
}

<value>

The value tag is used to describe a property. The summary tag is typically used to describe a property, but the value tag is used to convey the actual value the property represents.

Listing 5.16. Value XML Documentation Tag

/// <value>Property <c> TopLeftPoint</c> represents the Rectangles
/// top left <see cref="Point"/>.</value>
public Point TopLeftPoint
{
// ...
}

These are the ISO standard tags for XML documentation in C#. Most modern languages support some type of documentation that can be converted into an XML file. For VB.NET users, Microsoft has released a tool as a part of the Visual Studio.NET Powertoys called VB Commenter (http://www.gotdotnet.com/community/workspaces/viewuploads.aspx?id=112b5449-f702

-46e2-87fa-86bdf39a17dd). This tool allows VB.NET users to add similar style comments into their code using the triple comment (''') and to use the standard C# tags. Although this is currently a plug-in to Visual Studio.NET, the code is available on the gotdotnet Web site and could be converted into a standalone tool for use with something like Mono's Basic.NET or Sharpdevelop. In addition, it's likely to become a standard part of the language in the next release of .NET.