Version 1 of Sandcastle is a command line tool controlled through a set of configuration files. There are future plans to provide a graphical front end, integrated with Visual Studio. A number of third parties have developed GUI tools to simplify the process of using Sandcastle, including Eric Woodruff’s nDoc style GUI (Sandcastle Builder) which should help to make the transition to Sandcastle seamless for existing nDoc users such as myself.
The purpose of this article is to provide enough information for someone who hasn’t previously used a documentation compiler to start producing high quality documentation using Sandcastle.
Installation
The main Sandcastle web page provides links to the download, blog and other relevant resources. I downloaded and installed Sandcastle.msi (for the March CTP) via this site. Sandcastle is currently available free of charge under a CTP license. To run Sandcastle you will also need to have the .NET Framework version 2.0 installed, and the relevant HTML help compiler. Both of these are linked from the download page above if you don’t already have them installed. I also downloaded and installed Sandcastle Builder. This is a free to use application, with a very brief licence agreement.Sandcastle itself is command line driven, and so doesn’t create any Start menu items, but Sandcastle Builder will create a folder containing the application launch shortcut and a link to its own help. Both also create uninstall options in the Add or Remove Programs section of the Control Panel, and so can easily be removed at a later date.
Using Sandcastle Builder
The simplest way to use Sandcastle is through a user interface such as Sandcastle Builder. To demonstrate this I have created a trivial class library called MathLib, the code for which is shown below. I have included some basic documentation comments, and enabled the “XML Comments File” option in project settings so that the compiler will extract all the XML comments ready for conversion into documentation.namespace MathLib
{
/// <summary>
/// Performs basic arithmetic
/// operations
/// Not a very interesting class :-)
/// </summary>
public class Arithmetic
{
/// <summary>
/// Adds two number together
/// </summary>
/// <remarks>
/// Adds two numbers together.
/// Supports adding all integers.
/// </remarks>
/// <exception
/// cref="OverflowException">
/// Raised when the addition results
/// in an arithmetic overflow
/// </exception>
/// <param name="x">The first number to
/// add</param>
/// <param name="y">The second number to add</param>
/// <returns>The result of adding x and y</returns>
public int Add(int x, int y)
{
return x + y;
}
/// <summary>
/// Subtracts two numbers
/// </summary>
/// <remarks>
/// Subtracts two numbers.
/// Supports subtracting all integers.
/// </remarks>
/// <exception cref="OverflowException">
/// Raised when the subtraction
/// results in an arithmetic overflow
/// </exception>
/// <param name="x">The number to
/// subtract<b>from</b></param>
/// <param name="y">The number to subtract</param>
/// <returns>The result of subtracting y from x</returns>
public int Subtract(int x, int y)
{
return x - y;
}
}
To get started, open Sandcastle Builder from the start menu and select “New Project from Visual Studio Project…” from the “Project” menu. This will open a browse window that can be used to select either the solution file (.sln) or the project file (.csproj) for the MathLib class library. Once you select your project, you must also select a configuration (debug/release) so that Builder knows which assembly files you want it to use.
Before you can build the project, you must save the project file. Once you have done this, select “Build Project” from the “Documentation” menu. Sandcastle Builder will automatically identify the location of the Sandcastle installation and relevant help compilers, and use these in the build process. Even for a trivial example like this, the compilation process can take some time, and progress is displayed in the bottom panel.
Once the build process is complete, you can open the generated documentation file by selecting “View Help File” from the “Documentation” menu. You should now have some documentation that looks something like Figure 1.
Figure 1: MathLib documentation
Sandcastle Builder also comes with a console build utility, which can be added to the Visual Studio project as a post-build event. I added this for release mode only using the command:
"C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe" $(SolutionDir)\$(SolutionName).shfbBefore we look at how to improve and refine this output, we should take a more detailed look at the Sandcastle CTP itself.
Skipping the GUI?
In its CTP form, Sandcastle is actually a set of scripts, transforms and processes that work together to produce the documentation. The CTP ships with its own example in the “Examples/Sandcastle” folder under the main installation folder (usually “C:\Program Files\Sandcastle”). This is a good place to start, as it contains a batch file (“build_Sandcastle.bat”) with all the commands required to perform a complete build. It takes one parameter, either “vs2005” or “Prototype”.If you run this script, you can expect to sit back for a few minutes and watch an incredibly arcane stream of commands and output whip past in the console window before the build process completes. If you take a look at the script, you will see that Sandcastle builds documentation using a fairly long sequence of operations. Many of these use the “XSLTransform” application, which is a standards-based tool for XSL Transformations. There are also a couple of calls out to other batch files that copy files containing fixed content (e.g. icons) into the current build process.
There are two custom steps in the process. The first is a utility called “MRefBuilder” that uses reflection to examine the assembly being documented. The second is a utility called “BuildAssembler” that performs a lot of the hard work. It generates html for each entity using the documentation comments and reflected structure. It also uses a web service to create links to MSDN content where appropriate. Finally, the appropriate Help Compiler is invoked to produce the output.
I have tried modifying this script for my own projects, but gave up after an hour or so of messing around – life is just too short, and the exercise has convinced me that using a tool like Sandcastle Builder is the way forward, at least until the offering is a little more mature and better documented.
If Sandcastle Builder isn’t to your taste, there are a number of other options for automating the build process – see the box “Sandcastle Automation Options”.
Basic documentation configuration
Going back to our MathLib sample library, exploring the first build I created shows a number of obvious problems that I would have to solve before releasing this documentation to anyone. To fix these, I need to make a variety of changes in the Sandcastle Builder GUI:- The page title appears as “A Sandcastle Documented Class Library”. Change this by setting the Help Title property in the Help File section.
- The help file name is “Documentation.chm”. Change this by setting the HtmlHelpName property in the Help File section.
- The heading in the root node is “Namespaces”. Change this by setting the Root Namespaces Title property in the Help File section.
To provide summary information for namespaces, click the “Namespaces” button on the main form in Sandcastle Builder. This will open a new form giving you the option to enter a summary for each namespace (and to select which namespaces will appear in the output). There is a similar button (“Prj Summary”) to specify a summary for the top-level namespace view. Once you have made these changes, the documentation should be in an acceptable state, but there are still many ways to enhance it by adding more in-depth content and improving the formatting.
Supported tags
Visual Studio will create simple documentation comment templates for you automatically. When you have the cursor on the line before a definition, typing three slashes will produce the template. This will usually have a summary tag, and for some definitions will also have tags for describing the parameters and return values. When filling in these tags always remember that you are working in XML and therefore white space and line breaks will not be preserved.In order to produce the sort of rich documentation that developers have come to expect, you will need to add tags to those that are automatically inserted by Visual Studio. Tags are supported to format content, provide more detail, document exceptions or permissions, and to cross-reference other help content.
The Visual Studio Help system provides a useful list of the core supported tags in an article entitled “Recommended Tags for Documentation Comments” (search for this string). A summary appears in Table 1.
| Table 1: Visual Studio Recommended Tags | |
| Tag | Use |
| C | Wrap code fragments inline with standard text |
| Code | Wrap multi-line code fragments |
| Example | Wrap a multi-line code example |
| exception | Used to indicate exceptions that may be thrown |
| Include | Used to include external XML documentation, identifying the specific section using XPath |
| list/item | Creates a bulleted list |
| Para | Optional wrapper indicating distinct paragraphs for layout |
| Param | Describes a parameter |
| paramref | Wraps a reference to a parameter e.g. in summary or remarks sections |
| permission | Used to document permission requirements |
| Remarks | Detailed description |
| Returns | Describes the return value |
| See | Used inline within other tags to link to another section of the help file e.g. another class or method |
| Seealso | Used to provide a link in the “See Also” section of the help page |
| summary | Brief description that will appear in indices as well as the help page for that item. |
| typeparam | Describes a type parameter in a generic |
| typeparamref | Wraps a reference to a type parameter |
| Value | Describes the value of a property |
This is not the full story however, as Sandcastle supports a number of additional tags, most of which were originally introduced by nDoc and many of these are listed in Table 2.
| Table 2: Supported nDoc Tags | |
| Tag | Use |
| Event | Describes an event that may be raised within a member |
| Exclude | Causes the type or member to be excluded from the documentation |
| threadsafety | Used to describe the thread safety of types and members |
| Note | Formats its content as a note in the help file |
Enhancing appearance
Many tags in the documentation, and properties in the Sandcastle Builder GUI, support embedded HTML tags such as those for links, bold, italic, line break and horizontal rule. These can be used to enhance the appearance of your documentation, but should not be used in place of formatting provided through the standard documentation comment tags. There are also properties for you to add header and footer text, as well as specific information such as copyright and feedback email address. You may also wish to experiment with the “PresentationStyle” property. The default “Prototype” style was specifically developed for Sandcastle. The alternative is “vs2005” which mimics the Visual Studio 2005 help style.Sandcastle Builder installs with a number of modules that add capabilities to Sandcastle (remember, most of what it does is simply providing a front end). One of these is the rather useful “Code Block” component (see the Sandcastle Builder help file), which provides syntax highlighting for source code sections such as example code.
Adding content
The “AdditionalContent” property allows the user to specify additional content files for inclusion in the documentation file. Typically these would take the form of additional HTML content, perhaps a high level description or a license agreement that will sit outside the normal structure. The additional content dialog also allows you to edit the order and structure these items will have in the table of contents. Another application for it is loading in image files for logos or diagrams. Once loaded these can be referenced from inline comment tags or properties, using the standard html image tag. Additional content is stored by default in a directory one level above the automatically generated HTML content, and this should be reflected in the link url, e.g.
<img src="../mylogo.bmp"/>
Output formats
Sandcastle can be configured to build for HTML Help version 1 or 2, and can also be used to create a set of HTML documentation for deployment on a website. Sandcastle Builder supports any combination of these through the “HelpFileFormat” property.Conclusions
Sandcastle is a major initiative at Microsoft, and is already being used to generate much of its documentation. I have focused on using the technology rather than delving into its implementation, but those who do will find it to be highly configurable and based largely on open technologies such as XSLT and XPath. The current Community Technology Preview seems to be pretty robust, and is made simple to use by third party front-end applications such as Sandcastle Builder. This means that it should now be accessible to anyone who wishes to try it out over a lunch break.Sandcastle is likely to make a significant impact on the marketplace for documentation building tools, not least because it will be included with Visual Studio. It is a worthy successor to nDoc, but whether it can displace existing commercial products remains to be seen.
Ian Stevenson has been developing Windows software professionally for ten years, in areas ranging from WDM device drivers through to rapid-prototyping of enterprise systems. Ian currently works as a consultant in the software industry, and can be contacted at [email protected].
Sandcastle Automation OptionsI chose to use Sandcastle Builder as it is similar to nDoc, with which I am already familiar, and it can convert my existing nDoc projects. There are a number of other front-ends for Sandcastle however, including:
The main Sandcastle site provides links to a number of other GUI projects and command line tools, but at the time of writing most of these projects appeared to be dormant and did not support the latest CTP. |
Comments