13 September 2010

171953 views

90 0

Taming Sandcastle: A .NET Programmer’s Guide to Documenting Your Code

The most effective way to document .NET code so that others can understand it and use it, is to use XML Documentation and SandCastle. It isn't that easy. Michael Sorens produces the easy guide to the process that Microsoft never managed, and introduces several applications that help.

XML Documentation Comments: First Look.
Doc-Comment Elements.
Automate Your Doc-Comment Creation.
The Problem of Documentation Generation.
Sandcastle Help File Builder
Running Sandcastle Help File Builder
Sandcastle Help File Builder Configuration: First Look.
Rules for Embedding HTML..
Sandcastle for NDoc Users.
Sandcastle Considerations.
Conclusion.

Imagine it: You’ve spent months developing your new .NET application. At some point, you want to take an action within your application whenever files in a certain directory are changed by another process external to your program. You think about coding this “directory watcher” from scratch but, just as you are about to get started with the design, you come across the System.IO.FileSystemWatcher class. The hyperlink I have attached to that class name takes you to one entry point into the vast MSDN documentation collection for the API of .NET itself. The FileSystemWatcher does just what you need. Yet another building block from .NET now saves you substantial time, money, and effort towards reaching your goal. But having the building block is only half the story-the information on how to use it-the API-is the other half. If that comprehensive MSDN documentation wasn’t there to provide usage details, then most of you would find ways to cope: You might, for example, fire up .NET Reflector, examine class and method signatures or do some experimentation. Essentially what you would be doing-whether you write it down or not-is “documenting” the API for your own needs. Now, if you multiply the time you spend doing so by hundreds or thousands of other developers duplicate your effort, you’ll understand the scale of the wasted time. Because Microsoft took the time and effort to create and publish the API for all of the .NET libraries, this saves a huge amount of man-hours of work for you and other .NET developers. You want to extend the same courtesy to your potential user community, or fellow team-members.

The process to do this is quite poorly documented!

Figure 1 Integrating Sandcastle into your Build Process

The bulk of your work is documenting your code in Visual Studio. You then use SHFB to configure your documentation set and build it either from the GUI or from your build process to realize your finished documentation.

XML Documentation Comments: First Look

Documentation comments (or doc-comments) are comments in your code formatted with special markup to allow machine recognition during the build to propagate the information to two important consumers: the code editor’s Intellisense and the API generation that is the focus of this article.

Figure 2 illustrates how doc-comments support Intellisense for your custom classes. Say, for example, you have started typing “clo” in either the “before” or “after” frame. Intellisense pops up and indicates the first such item is ClockBackColor. Before doc-comments were added to the source code, the tooltip for ClockBackColor does not provide much additional information, just the base type Color. But after adding comments to the library and recompiling, the tooltip in this code that uses the library now shows a description.

Figure 2 How Doc-Comments Integrate into Intellisense

The top frame shows how Intellisense recognizes your library component but nothing more. Once you have it documented, Intellisense can give the user more information as shown in the bottom frame.

This added description came from adding special comments to the source code. Here’s the relevant code I typed in:

/// <summary>

/// Sets the background color of the clock display.

/// </summary>

public Color ClockBackColor

{

get { return clockBackColor; }

set { clockBackColor = value; clockLabel.BackColor = clockBackColor; }

}

The contents of that <summary> element appear in the Intellisense tooltip-and only the contents of the <summary> element-other elements you add for your external documentation set will not appear in Intellisense. For the doc-comments to contribute either to Intellisense or to external documentation, however, you must explicitly enable XML documentation generation in your project properties-see Figure 3 (Note that you are enabling the XML documentation generation for your library project, not for your application that consumes the library.)

Figure 3 Enabling Documentation Generation in Visual Studio

Doc-Comment Elements

The example above showed just the <summary> doc-comment tag, which is the most used tag because virtually every member (class, method, property, event) you create must have one. The table below shows all the other tags you need to create effective and complete documentation.

Tag	Usage is…	Purpose
Main Sections
<summary>	Required	A short (usually one-line) description of the member. This appears at the top of the member’s web page as well as on its parent summary pages. For example, the <summary> of a method appears on its parent Methods page while the <summary> of a class appears on its parent Namespace page. Also used to populate an Intellisense tooltip for the object when embedded in a larger project.
<remarks>	Optional	A detailed description of the member.
<example>	As needed	A substantial example in its own section; trivial examples could be included in the <remarks> section.
<seealso>	As needed	Adds a link to associated documentation.
Member Descriptions
<param>	Required for each parameter	Describes a parameter of a method. Also displayed in Intellisense.
<typeparam>	Required for each generic type parameter	Describes a type parameter of a generic type or method.
<returns>	Required for each method that returns a value	Describes the return value of a method.
<exception>	Optional	Describes an exception that could be thrown by a method.
<value>	Required	Describes the value that a property represents.
<permission>	Optional	Documents the access level of a method.
Text Elements
<include>	As needed	Block-level element. Embed all or part of another file into the current doc-comments.
<para>	As needed	Block-level element. Defines a paragraph.
<list>	As needed	Block-level element. Creates a list in one of several different formats. (Note that the MSDN page lists bullet, number, or table lists, but does not include the definition list. See discussion here).
<code>	As needed	Block-level element. Specifies to format the content as code.
<c>	As needed	Inline element. Specifies to format the content as code.
<see>	As needed	Inline element. Defines a link to a page within the same documentation set (cref attribute) or to an external web page (href attribute).
<paramref>	As needed	Inline element. References a parameter of a method.
<typeparamref>	As needed	Inline element. References a type parameter of a generic type.

For more details, see MSDN’s Recommended Tags for Documentation Comments and Dynicity’s excellent XML Documentation Comments Guide.

Documentation comments:

Begin with a triple virgule rather than a double virgule (///) for single-line comments or, for multi-line comments, include a double-asterisk after the opening virgule (/** . . . */ ). See Delimiters for Documentation Tags.
Are written in a specific XML dialect.
Are syntactically validated at compile time.

Automate Your Doc-Comment Creation

The objective of this article is to describe how to go about automating the process of generating a finished documentation set. However I must mention, in passing, some powerful techniques to assist the process of doc-comment writing without which the task of writing all those doc-comments would be overwhelming.

There are several levels at which you can get assistance in the documentation process.

Level 1: Word-level Assist: Intellisense

The first tool is Intellisense, which recognizes basic doc-comment syntax. Once you are inside a doc-comment type an opening left angle bracket (<). Visual Studio displays XML tags valid for the context. Referring back to the previous code example, place your cursor after the closing tag of the <summary> element, press return, then type an opening angle bracket. Intellisense pops up several possible keywords; typically <result> is the element to use here. Type “r”, then press tab to fill in the word. Type “>” to close the tag and Visual Studio adds the closing tag.

Level 2: Foundation-laying Assist: Smart Comment Editing

The next step up is also built-in to Visual Studio: smart comment editing. On the line just above a method, property, or class declaration, type a triple virgule and Visual Studio automatically supplies an empty <summary> element (where you describe the member’s purpose in one line) followed by other relevant doc-comment elements. (Note that if you have attributes on the given member you must be positioned just above those rather than above the member name.) Say, for example, you have a method that returns a value and takes several parameters:

public int DeterminePageBufferSize(

int initialPageBufferSize,

string host,

int port,

int timeout,

bool smartTrace)

{

// code here . . .

}

Place your cursor on the line above the first line of code shown, press three virgules (///), and Visual Studio inserts boilerplate commentary for all the required doc-comment elements:

/// <summary>

///

/// </summary>

/// <param name="initialPageBufferSize"></param>

/// <param name="host"></param>

/// <param name="port"></param>

/// <param name="timeout"></param>

/// <param name="smartTrace"></param>

/// <returns></returns>

Note that you can control whether smart comment editing is enabled via the Options dialog for C# (see Figure 4).

Figure 4 Enabling Smart Comment Editing in Visual Studio

Level 3: Supercharged Assist: GhostDoc

Smart comment editing can save you substantial amounts of typing. But a third-party plug-in called GhostDoc-available for Visual Studio 2005, 2008, and 2010-not only provides the boilerplate that smart comment editing does, it also fills in the boilerplate!

Consider again the previous DeterminePageBufferSize method:

public int DeterminePageBufferSize(

int initialPageBufferSize,

string host,

int port,

int timeout,

bool smartTrace)

{

// code here . . .

}

Place your cursor on the first line of the method and press Control-Shift-D (or other key combination you may have selected) to invoke GhostDoc and you get this:

/// <summary>

/// Determines the size of the page buffer.

/// </summary>

/// <param name="initialPageBufferSize">Initial size of the page buffer.</param>

/// <param name="host">The host.</param>

/// <param name="port">The port.</param>

/// <param name="timeout">The timeout.</param>

/// <param name="smartTrace">if set to <c>true</c> [smart trace].</param>

/// <returns></returns>

public int DeterminePageBufferSize(

int initialPageBufferSize,

string host,

int port,

int timeout,

bool smartTrace)

{

// code here . . .

}

GhostDoc has not only enumerated each required element, it has filled them in. Notice how it parses the Pascal-casing of the names to separate and re-arrange words, deriving “Determines the size of the page buffer” from the “DeterminePageBufferSize” name. Items that it knows need polishing or correction are marked in square brackets, as in the smartTrace parameter comment above. It describes its Boolean nature but does not quite know what to say it does. GhostDoc has a complex-and configurable-set of rules to do this seeming magic. It does not always guess correctly, but it does remarkably well. The better names you use, the more success you will have with this timesaving tool.

Overridden and subclassed members are handled particularly nicely by GhostDoc as well. This next method exists inside a subclassed System.Windows.Controls.UserControl. I generated the method with just a couple keystrokes: “o”, “v”, space, “o”, “n”, “i”, tab. Then I generated the complete doc-commentary with GhostDoc’s single keystroke command: Control-Shift-D.

/// <summary>

/// Raises the <see cref="E:System.Windows.FrameworkElement.Initialized"/> event.

/// This method is invoked whenever

/// <see cref="P:System.Windows.FrameworkElement.IsInitialized"/> is

/// set to true internally.

/// </summary>

/// <param name="e">The <see cref="T:System.Windows.RoutedEventArgs"/>

/// that contains the event data.</param>

protected override void OnInitialized(EventArgs e)

{

base.OnInitialized(e);

}

Note that GhostDoc also installs a submenu under the Tools menu, so you can invoke its function through the menu sequence Tools >> GhostDoc >> Document This if you prefer.

The Problem of Documentation Generation

Once you have completed the considerable, but important, task of documenting your entire code base, and then building your solution so that it compiles cleanly with Visual Studio, you should now have an XML file for each project that you instrumented. Until recently, that was the easy part. The more arduous task was to use these intermediate files to provide documentation. Several years ago, a third-party tool called NDoc (authored by Kevin Downs) let you convert these intermediate XML files to a finished documentation set. NDoc, however, was designed for .NET version 1 and was not compatible with subsequent .NET releases! There was a port for .NET 2.0 (authored by Jonas Lagerblad), but the hyperlinks for that have dried up completely at the time of writing. Even so, NDoc did persevere until 2006, according to Wikipedia, just at the time that Sandcastle succeeded it.

Sandcastle was developed by Microsoft and is, in fact, what they use to generate the MSDN documentation. Sandcastle wasn’t easy to use. According to Wikipedia, “Sandcastle is a set of command line programs, configuration files, build components and XSLT transformation files that work together to convert XML-based documentation into help topics that are fit for viewing in a help system.” As that description suggests, it is not a tool with a simple interface. Using Sandcastle was such a challenge that several independent developers created wrapper applications. Here are the ones I know about.

Product	Version	Latest release	Downloads
Sandcastle Help File Builder	1.9.1.0	July 2010	9,000*
DocProject	1.11.0	June 2008	29,000
Sandcastle GUI	1.54	March 2010	??
Sandcastle CHM	??	August 2006	??

*This download count refers only to the current version. Counts for prior versions are not included.

The first two are evidently packaged as industrial strength products, while the other two are more informal. If you search the web you will see that both Eric Woodruff’s Sandcastle Help File Builder (SHFB) and David Sexton’s DocProject are well-respected. I chose SHFB some time ago and have not been disappointed. It has a clean interface, does the job well, and has great support. While I was converting a good size documentation repository from NDoc to Sandcastle I encountered a number of issues and was able to communicate easily and effectively with the author who either told me what I was doing wrong, or promptly enhanced or fixed SHFB with the deficiencies I identified. To help you decide which of these might work best for you, take a look at the individual websites at the links above. Ideally I could point you to several articles that compare the two-I found only two of any substance, a blog entry by Ben Hall and this post by SHFB’s creator Eric Woodruff (it takes a very fair approach). If you elect to use SHFB, then the remainder of this article should be of even greater interest!

Sandcastle Help File Builder

SHFB provides a GUI front end to Sandcastle in the guise of a file navigator in combination with a large property pane. You use the file navigator to add projects to your configuration and you use the property pane to adjust the numerous settings of Sandcastle. Once you set those you do a build and SHFB directs Sandcastle to generate your completed documentation set.

Figure 5 The Sandcastle Help File Builder GUI Window

Even with this helpful wrapper, I still cannot call Sandcastle “easy” to use, but it is easier! A case in point-installation. You actually need to install at a minimum these three separate components, each from a different website:

Sandcastle – the core components
Sandcastle Styles – patches to presentation style files for bug fixes and enhancements
Sandcastle Help File Builder – the GUI

The Sandcastle Styles package is a collection of patches to the core Sandcastle’s presentation component. If you don’t install it you may get either poor or even faulty rendering of your output, possibly without realizing it. The SHFB Installation Instructions certainly mention this, but you might miss that. You should read these instructions, along with Sandcastle Style’s Getting Started, to guide you in your installation. Also, go to the SHFB Documentation and view the FAQ page and the Known Issues and Limitations page. This base installation of Sandcastle generates documentation as a web site, just like MSDN. If you want a different form (chm, Hxs, or mshc help files) you must install some additional components that Sandcastle will use to generate the documentation.

I mentioned, at the beginning, the irony that .NET documentation generation is itself poorly documented. I am not the only one who noticed this. There is a user-posted comment at the bottom of Sandcastle’s main documentation page musing over the fact that most of the documentation links on the site point to empty content. That is why Sandcastle Help File Builder exists, I suppose! SHFB is, by contrast, well documented. Sandcastle Styles also is well documented. Its architecture page includes both a very good architectural diagram of Sandcastle and its modes of operation. Other useful links to remember include the MSDN Sandcastle page and the Sandcastle blog. Tim Stanley’s interesting blog entry covers the history and future of NDoc and Sandcastle.

Running Sandcastle Help File Builder

Once you do all the preparation work, get Sandcastle installed, and finish reading this article, then running SHFB is quite straightforward.

In the project explorer, open the context menu on Documentation Sources, then add your project files (*.csproj)
Set SHFB properties to your preferences-these are the key ones that are discussed elsewhere in this article:
1. Select the type of documentation set you wish to build (Project Properties >> Build category >> HelpFileFormat): HtmlHelp1, MSHelp2, MSHelpViewer, or Website. Except for the Website choice, you will need to install additional external components that SHFB needs to invoke.
2. Select the presentation style (Project Properties >> Help File category >> PresentationStyle): vs2005 (the default), hana, or prototype. See Style Choices and Code Display Issues.
3. Select the file naming method (Project Properties >> Help File category >> NamingMethod): Guid (the default), MemberName, or HashedMemberName. The middle choice-MemberName-is typically the most useful. See File Naming Conventions.
4. Select the configuration to match your Visual Studio build: debug (the default) or release. See Specifying Debug or Release Configuration.
Build.
View your output. You could do this manually by just opening up the correct file from Windows Explorer. For the website format, this is Index.html in your output directory. But SHFB lets you do this easily from within the application. The Documentation >> View Help File menu provides several choices to open the formats you have built. You can even set a property to auto-open upon a successful build.

Also see the SHFB documentation page then drill down to Getting Started >> Walkthrough: Creating Your First Project.

As I was finishing this article my editor suggested one other product I might want to mention. Help and Manual is a documentation management tool that lets you take Word, help, text or Sandcastle files as input and generate PDF, e-Book, help (and other) formats as output. As just mentioned, SHFB lets you natively generate four different formats, but neither PDF nor e-Book is among them, so my interest was piqued. Help and Manual looks promising: I was able to import a compiled Html help file (.chm) generated by SHFB in a couple clicks then generate a PDF or e-Book from that with a couple more clicks. These output formats retained the structure of the original reasonably well. I do not (yet) support their claims on how easy it is to use Help and Manual, though, since I ran into some issues importing from a couple different sources (chm and HTML) and was not able to do import from my Sandcastle configuration. As it is a sophisticated product, and I spent just a short time with it, I attribute this to the learning curve needed to use the product effectively.

Sandcastle Help File Builder Configuration: First Look

It helps to have a concrete example in order to explain a documentation generator. I use illustrations from my open source .NET library because you have immediate access to the finished, generated documentation here (Figure 6 shows the top-level page).

Figure 6 Top-Level Documentation Page Generated by Sandcastle

Download the CleanCode C# library and you have the fully instrumented source files to examine the doc-comments for anything you want to review in detail. Furthermore, you can examine my build file (I use ant) in several visualizations. The raw XML file is here with an XSL-stylized mask on it (just do View Source in your browser to see the raw XML if you prefer). A more API-style view of it is available here. The build file is (overly) complex; the documentation generation is controlled by the csharp.doc target in the ant file. That runs through an assortment of bookkeeping details but eventually gets to this step that does the actual Sandcastle processing:

<target name="csharp.doc.main"

depends="csharp.doc.checkIfRequired"

unless="csharpdocBuild.notRequired">

</exec>

</target>

Or, if you do not “speak” ant, here is the essence from the command line:

\WINDOWS\Microsoft.NET\Framework\v3.5\MSBuild.exe

/p:Configuration=Release

CleanCode.shfbproj

You’ll have noticed that the build step is nothing more than calling the standard .NET msbuild utility with the SHFB configuration file. It is not as complicated as you might think. Here is the raw file for my libraries-the only thing I have omitted is the content of the FooterText element because that is quite convoluted (not because of SHFB, but rather because of all the stuff I want to put in the footer of my HTML pages):

<Project DefaultTargets="Build"

xmlns=http://schemas.microsoft.com/developer/msbuild/2003

ToolsVersion="3.5">

<PropertyGroup> <Configuration

Condition=" '$(Configuration)' == '' ">Debug</Configuration>

<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>

<!-- AssemblyName, Name, and RootNamespace are not used by SHFB

but Visual Studio adds them anyway -->

<AssemblyName>Documentation</AssemblyName>

<RootNamespace>Documentation</RootNamespace>

<Name>Documentation</Name>

<OutputPath>C:\usr\tmp\CleanCode doc\</OutputPath>

<HtmlHelpName>CleanCode C# Libraries API</HtmlHelpName>

<HelpTitle>CleanCode C# Libraries v1.0.0 API</HelpTitle>

<HelpFileFormat>Website</HelpFileFormat>

<MissingTags>Summary, Parameter, Returns, Value,

AutoDocumentCtors, Namespace, TypeParameter</MissingTags>