Generating Documentation for an Assembly

Documentation is important, there's little doubt about that. Once all the developers who have worked on a project have moved on to something new, documentation is all you'll have left to help you make sense of the design decisions made at the code level, and how these fit with the business model you will have made during the early stages of the project.

Using C# and Visual Studio .NET, there are two features we can use to make this easier. The first allows us to insert some descriptive documentation into each compiled assembly that gets deployed with the final application. Here is a place we can put copyright notices, version information, trademarks, descriptions etc. that will all help to identify exactly what the assembly contains.

The second feature we can use concerns documentation of the code itself. This is much more valuable to other developers, especially if we have produced an assembly designed for reuse – for example, a class library. We'll look at these two features in turn.

Using Assembly-level Attributes

In the previous section, we described how to create a shared assembly and install it into the Global Assembly Cache. The GAC insists that the assembly is strongly named, which means the assembly must contain public key information. As we saw earlier, the way to provide this public key is through the [assembly: AssemblyKeyFile] attribute. For example:

    [assembly: AssemblyKeyFile("C:/classdesign/chapter08/MyKey.snk")] 

As well as specifying the name of the public-private key pair file, we can also specify additional information, such as the following:

• Free-format title of the assembly

• Description of the assembly

• Company name

• Product name information

• Copyright information

• A trademark

The following example shows how to define this information. The source code for this example is located in the Documentation download folder. The documentation information is defined in the file AssemblyInfo.cs:

    using System.Reflection;    using System.Runtime.CompilerServices;    //    // General Information about an assembly is controlled through the    // following set of attributes. Change these attribute values to    // modify the information associated with an assembly.    //    [assembly: AssemblyTitle("My Assembly")]    [assembly: AssemblyDescription("My cool assembly")]    [assembly: AssemblyCompany("My Company Inc.")]    [assembly: AssemblyProduct("My Product")]    [assembly: AssemblyCopyright("(c) My Company, 2002")]    [assembly: AssemblyTrademark("TM My Company")]    //    // Version information for an assembly consists of four values:    //    //    Major Version    //    Minor Version    //    Build Number    //    Revision    //    // You can specify all the values or you can default the Revision    // and Build Numbers by using the '*' notation    [assembly: AssemblyVersion("1.0.*")] 

We can build this application using the command-line compiler from the Documentation folder in the code downloads for this book. Enter the following command:

    C:\Documentation>csc /out:Documentation.exe *.cs 

We can view the properties for the compiled assembly in Windows Explorer: select the assembly file in Windows Explorer, and select Properties from the Shortcut menu. For example, in Windows 2000, the Properties window shows the following information:

When we click on the Version tab, we can see detailed information about the assembly. For example, the Comments field appears as follows:

XML Documentation

The Visual Studio .NET C# compiler provides a unique command-line switch, /doc, which produces an additional output file when it compiles your code. The output file is in XML format and contains selected comments collected from your source code. For it to do this, the comments must be written in a particular format. In C#, this is done using three consecutive "/" characters, together with an XML tag name. For example, we'll add a few such comments to the types we defined in the file books.cs earlier:

    using System.Collections;    namespace Books    {      /// <summary>      /// Inventory is a singleton class. It maintains a list of      /// Books, indexed by ISBN.      /// </summary>      /// <remarks>      /// Use the static property Instance to obtain a reference to      /// the singleton. Then use the factory method CreateBook      /// to create and add individual Books.      /// </remarks>      public class Inventory      {        /// <summary>        /// Private member field containing a reference to the        /// singleton instance.        /// </summary>        private static Inventory mInstance;        /// <summary>        /// Hashtable containing a collection of Book objects.        /// </summary>        private Hashtable mLibraryBooks;      // and so on...    } 

Note the following in the above code:

• The /// comments are added immediately before the type or member to which they refer.

• If we type /// in Visual Studio .NET, the <summary></summary> tags are automatically added for us.

To see the XML documentation file generated by these comments, we can either compile the code using the C# command-line compiler with the /doc switch, or we can configure Visual Studio .NET to do this for us. The command-line compiler can be invoked like this:

    C:\> csc /t:library /doc:documentation.xml books.cs 

As books.cs contains just type definitions, we have compiled it as a library using the /t switch. The /doc switch requires a filename to be used for writing the generated XML. In the example above, we have specified the file documentation.xml.

Alternatively, from Visual Studio .NET, right-click on the project in the Solution Explorer and select Properties from the menu. Then select Configuration Properties and enter documentation.xml against the XML Documentation File option.

In either case, when the project is compiled, the following XML is generated in the file documentation.xml:

    <?xml version="1.0"?>    <doc>      <assembly>        <name>DocExample</name>      </assembly>      <members>        <member name="T:Books.Inventory">          <summary>          Inventory is a singleton class. It maintains a list of          Books, indexed by ISBN.          </summary>          <remarks>          Use the static property Instance to obtain a reference to          the singleton. Then use the factory method CreateBook          to create and add individual Books.          </remarks>        </member>        <member name="F:Books.Inventory.mInstance">          <summary>          Private member field containing a reference to the          singleton instance.          </summary>        </member>        <member name="F:Books.Inventory.mLibraryBooks">          <summary>          Hashtable containing a collection of Book objects.          </summary>        </member>        <!-- etc. -->      </members>    </doc> 

You can see that the <summary> and <remarks> tags we typed have been extracted and placed with the C# type to which they refer.

The documentation for Visual Studio .NET defines a number of XML tags that are understood by the IDE and assisted by IntelliSense prompting. Also, it's useful to know that the comments in the <summary> elements are actually used by IntelliSense to describe fields, properties, and methods from your own classes during development.

You are not limited to the tags documented by Visual Studio .NET, you can actually use any valid XML tags in the /// comments and these will be extracted correctly by the compiler. This allows you to produce any format of XML you like, which can be subsequently processed into readable documentation using a suitable XSLT stylesheet.

In fact, Visual Studio .NET can do this too, although, at the time of writing, only the <summary> and <remarks> tags are processed correctly by the IDE to generate HTML format documentation using the option Build Comment Web Pages from the Tools menu. Using this option with our commented source code, we can produce HTML documentation that looks similar to this:

This is a great step forward from producing documentation manually and has the advantage that the feature is an integral part of the IDE.

It is a little frustrating that the current version of Visual Studio .NET does not support all of the XML tags documented. However, there are third-party tools that can process the generated XML and produce much more complete documentation. One such tool is called NDoc, which allows you to generate documentation based on the above mentioned XML. NDoc can be downloaded from http://ndoc.sourceforge.net. This software deserves a quick look for the following reasons:

• It's free

• As an open source product, it can be tailored for your own use

• It's written entirely in C# and documented using XML tags

• Documentation can be generated in compiled HTML format (CHM) and is visually styled like MSDN documentation.

One added benefit is that NDoc uses reflection to traverse the class hierarchy of the types defined in your assemblies and can produce documentation for inherited members too. The results can be quite satisfying. For example, we can load NDoc and select the Visual Studio .NET project – DocExample – used above. NDoc recognizes the assemblies produced by the solution and gives us some options to change the format of the generated documentation:

A simple mouse click then generates a documentation file for us in compiled HTML format. NDoc traverses the class hierarchy for all of the types defined in the assemblies we've specified, and builds the documentation in a similar format to that used for the .NET Framework documentation in MSDN: