Making Use of XML Documentation


This chapter has mentioned in several places that there is much more that you can do with XML documentation than simply using it to supply IntelliSense information to VS — although this isn't to say that customized IntelliSense isn't an extremely useful feature.

Perhaps the simplest thing you can do with XML documentation is to ship it with your assemblies and leave it up to other people to make use of it, but this is far from ideal. In this section, you'll look at some of the possibilities for getting the most out of your documentation.

Programmatically Processing XML Documentation

The most obvious thing to do with XML documentation is to make use of the wealth of XML tools in the .NET namespaces. Using the techniques and classes you saw in Chapter 23, it is possible to load XML documentation into an XmlDocument object. The following Try It Out is a simple console application that does just this.

Try It Out – Processing XML Documentation

image from book
  1. Create a new console application called XMLDocViewer in the directory C:\BegVCSharp\ Chapter28.

  2. Add a using statement for the System.Xml namespace to Program.cs:

    using System; using System.Collections.Generic; using System.Text; using System.Xml; 
  3. Modify the code in Main() as follows:

    static void Main(string[] args) { // Load XML documentation file XmlDocument documentation = new XmlDocument(); documentation.Load(@"..\..\..\..\DocumentedClasses" + @"\DocumentedClasses\bin\debug\DocumentedClasses.xml"); // Get <member> elements. XmlNodeList memberNodes = documentation.SelectNodes("//member"); // Extract <member> elements for types. List<XmlNode> typeNodes = new List<XmlNode>(); foreach (XmlNode node in memberNodes) { if (node.Attributes["name"].Value.StartsWith("T")) { typeNodes.Add(node); } } // Write types to the console. Console.WriteLine("Types:"); foreach (XmlNode node in typeNodes) { Console.WriteLine("- {0}", node.Attributes["name"].Value.Substring(2)); } Console.ReadKey(); }

  4. Execute the application. The result is shown in Figure 28-9.

    image from book
    Figure 28-9

How It Works

This example demonstrates the basics of loading and processing an XML documentation file in C# code. You start by loading in a documentation file, which in this case is the one generated by the DocumentedClasses type library:

XmlDocument documentation = new XmlDocument(); documentation.Load(@"..\..\..\..\DocumentedClasses"    + @"\DocumentedClasses\bin\debug\DocumentedClasses.xml"); 

Note that the string concatenation used here isn't necessary, but is done purely to make the code easier to read on a narrow page!

Next, you get a list of all the <member> elements using the simple XPath expression //member:

XmlNodeList memberNodes = documentation.SelectNodes("//member");

Once you have a list of <member> elements, you can search through them, looking for those that start with a T to get the elements that refer to types, and placing them into a List<XmlNode> collection:

List<XmlNode> typeNodes = new List<XmlNode>(); foreach (XmlNode node in memberNodes) {    if (node.Attributes["name"].Value.StartsWith("T"))    {       typeNodes.Add(node);    } }

You could of course achieve this in a single step, using a more advanced XPath expression that included an attribute check, but why overcomplicate things?

Finally, you output the names of the types found to the console:

Console.WriteLine("Types:"); foreach (XmlNode node in typeNodes) {    Console.WriteLine("- {0}", node.Attributes["name"].Value.Substring(2)); }

There's a lot more that you could do here, since navigating and processing XML files in .NET isn't a complicated process. However, since there are better ways of handling XML documentation, as you'll see in the next two sections, there is no real need to take this example further.

image from book

Styling XML Documentation with XSLT

Since XML documentation is, by definition, XML, there is plenty of scope for using XSLT transformations to convert your XML into HTML, or even to use XSLT formatting objects to create printable documentation.

At this point, we'd like to defer to the true master of (and driving force behind) C# — Anders Hejlsberg. He has published an XSLT document and associated CSS stylesheet to turn XML documentation files into stylish HTML. These two files, doc.xsl and doc.css, can be found in the downloadable code for this chapter in the directory XSLTStyledXMLDocumentation. All that is required to use these files is to add a processing directive to your XML documentation files as follows:

<?xml version="1.0"?> <?xml:stylesheet href="doc.xsl" type="text/xsl"?> <doc>   ... </doc> 

You'll also find a version of DocumentedClasses.xml in the XSLTStyledXMLDocumentation directory that includes this directive. A sample of the result is shown in Figure 28-10.

image from book
Figure 28-10

The styling isn't perfect — <seealso> elements in particular don't come out right, and you can see in the screenshot that there are problems with <code> formatting — but overall it's pretty impressive. The files make an excellent starting point should you wish to make a Web page of your documentation. The way that the <see> elements link to anchors on the page is particularly good.

Perhaps the biggest problem with doing things this way is that everything appears in a single HTML page, which could get very large indeed.

NDoc

The last way of processing XML documentation is the most powerful of the lot. NDoc is a third-party tool that is capable of converting your documentation into a number of formats, including MSDN-style help files.

To obtain NDoc (for free!), head to http://ndoc.sourceforge.net. At the time of writing, the current version is 1.3, and even though it hasn't yet been upgraded for VS2005, it's still functional (as long as you use the .NET Framework 1.0 version). The authors of NDoc (Don Kackman et al.) are currently working on a new version, which may well be released by the time you read this.

So, why all this fuss about something that we've just said is an old piece of software? The simplest way to answer this is to look at the results. Included in the DocumentedClasses class library project is a help file that was generated using this tool, called Documentation.chm. A sample screenshot of this help file is shown in Figure 28-11.

image from book
Figure 28-11

As you can see, the result pretty much justifies XML documentation in itself. Everything you expect is there, including quite a bit more than is in the source XML file. A lot of information, such as the names- pace hierarchy for your namespaces and so on, is inferred from what is there.

We won't go into details about how to use NDoc here, partly because it's so simple to use that it hardly merits a discussion, and partly because the interface and capabilities may change with a VS2005 release. But we would strongly urge you to download it and find out for yourself just how useful this tool is.




Beginning Visual C# 2005
Beginning Visual C#supAND#174;/sup 2005
ISBN: B000N7ETVG
EAN: N/A
Year: 2005
Pages: 278

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net