Chapter 5: Advanced C# Class Construction Techniques

This chapter rounds out your introduction to the core aspects of the C# language by examining a number of advanced (but extremely useful) syntactic constructs. To begin, you learn how to construct and use an indexer method.

XML-Based Documentation

This final topic of this chapter is by no means as mentally challenging as the .NET delegation protocol, and is not necessarily an "advanced" technique. Nevertheless, your next goal is to examine a technique provided by C#, which enables you to turn your source code documentation into a corresponding XML file. If you have a background in Java, you are most likely familiar with the javadoc utility. Using javadoc, you are able to turn Java source code into an HTML representation. The C# documentation model is slightly different, in that the "source code to XML formatting" process is the job of the C# compiler (csc.exe) rather than a standalone utility.

So, why use XML to represent your type definitions rather than HTML? The primary reason is that XML is a very enabling technology. Given that XML separates raw data from the presentation of that data, you (as a programmer) can apply any number of XML transformations to the raw XML. As well, you could programmatically read the XML file using types defined in the .NET base class library.

When you wish to document your types in XML, your first step is to make use of a special comment syntax, the triple forward slash (///) rather than the C++ style double slash (//) or C-based (/*... */) syntax. After the triple slash, you are free to use any wellformed XML tags, including the following predefined set (see Table 5-3).

Table 5-3. Stock XML Tags

Predefined XML Documentation Tag	Meaning in Life
<c>	Indicates that text within a description should be marked as code
<code>	Indicates multiple lines should be marked as code
<example>	Used to mock up a code example for the item you are describing
<exception>	Used to document which exceptions a given class may throw
<list>	Used to insert a list into the documentation file
<param>	Describes a given parameter
<paramref>	Associates a given XML tag with a specific parameter
<permission>	Used to document access permissions for a member
<remarks>	Used to build a description for a given member
<returns>	Documents the return value of the member
<see>	Used to cross-reference related items
<seealso>	Used to build an "also see" section within a description
<summary>	Documents the "executive summary" for a given item
<value>	Documents a given property

The following is a very streamlined Car type with some XML-based comments. In particular, note the use of the <summary> and <param> tags:

/// <summary>
/// This is a simple Car that illustrates
/// working with XML style documentation.
/// </summary summary>
public class Car
{
    /// <summary summary>
    /// Do you have a sunroof?
    /// </summary summary>
    private bool hasSunroof = false;
    /// <summary summary>
    /// The ctor lets you set the sunroofedness.
    /// </summary summary>
    /// <param name="hasSunroof"> </param param>
    public Car(bool hasSunroof)
    {
        this.hasSunroof = hasSunroof;
    }
    /// <summary summary>
    /// This method allows you to open your sunroof.
    /// </summary summary>
    /// <param name="state"> </param param>
    public void OpenSunroof(bool state)
    {
        if (state = true && hasSunroof = true)
        {
            Console.WriteLine("Put sunscreen on that bald head!");
        }
        else
        {
            Console.WriteLine("Sorry...you don't have a sunroof.");
        }
    }
    /// <summary summary>
    /// Entry point to application.
    /// </summary summary>
    public static void Main()
    {
        SimpleCar c = new SimpleCar(true);
        c.OpenSunroof(true);
    }
}

Once you have your XML documentation in place, you can specify the /doc flag as input to the C# compiler. Note that you must specify the name of the XML output file as well as the C# input file:

csc /doc:simplecar.xml simplecar.cs

As you would hope, the Visual Studio.NET IDE enables you to specify the name of an XML file to describe your types. To do so, click the Properties button from the Solution Explorer window (see Figure 5-12).



Figure 5-12. Activating the Project Properties dialog

Once you've activated the Project Properties dialog, select the Build option from the Configuration Properties folder. Here you will find an edit box (XML Documentation File) that enables you to specify the name of the file that will contain XML definitions for the types in your project (which is automatically regenerated as you rebuild your project).

Viewing the Generated XML File

If you were now to open the simplecar.xml file from within the Visual Studio.NET IDE, you would find the display shown in Figure 5-13.



Figure 5-13. The Visual Studio.NET XML viewer

If you were to select the XML button from the XML editor window, you would find the raw XML format. Be aware that assembly members are denoted with the <member> tag, fields are marked with an F prefix, types with T, and members with M. Table 5-4 provides some additional XML format characters.

Table 5-4. XML Format Characters

Format Character	Meaning in Life
N	Denotes a namespace
T	Represents a type (i.e., class, interface, struct, enum, delegate)
F	Represents a field
P	Represents type properties (including indexers)
M	Represents method (including such constructors and overloaded operators)
E	Denotes an event
!	Represents an error string that provides information about the error. The C# compiler generates error information for links that cannot be resolved.

At this point, you have a raw XML file that can be rendered into HTML using an XSL style sheet or programmatically manipulated using .NET types. Although this approach gives you the biggest bang for the buck when it comes to customizing the look and feel of your source code comments, there is another alternative.