Everyone wants terrific looking help files to document their code, but creating them can be time consuming and difficult. However, by using some simple techniques, combined with a program called Sandcastle, you can largely automate the process of creating a help file. Yes, you’ll still need to do a little extra work, but nothing too difficult. When you complete this article, you’ll be able to create a help file to document the code for the most complicated application in a relatively short time and with few (if any) errors. The secret to this technique is not to use Sandcastle alone. Instead, you combine Sandcastle with the Sandcastle Help File Builder. The two products together really do reduce the labor involved in creating your next help file.

The example application used for this article isn’t important. It could be any application on your hard drive. However, because we need something to talk about, I created an application named ApplicationComments. All this application does is use a special class to perform some string manipulations and then display those strings on screen. It consists of a standard class, an extension class for the String class, and a test application—nothing too complicated.

It Starts with the XML File

Before you can do anything, you need to tell Visual Studio to create an XML file based on special comments in your application. Visual Studio doesn’t perform this task by default. To perform this task, you need to choose Project | <Project Name> Properties. You’ll see a project Properties window. Select the Build tab and you’ll see a display similar to the one shown in Figure 1.

Figure 1: Set the application up to create an XML file as output.

Notice the Output section near the bottom of the window. Normally, all you need to do is check the XML Documentation File option and close the window. The next time you build your application, Visual Studio also generates the XML file for you. However, you can also choose to change the Output Path property when you want to place the XML file in a centralized location.

Adding XML Comments

Now that you have the application setup to build the XML file, you need to add special XML comments to every one of the entries. A typical XML comment consists of nothing more than a summary of what the property, event, or other element does. Here’s a typical example for a property.

/// <summary>
/// Contains the current changed value of the string.
/// </summary>
public string CurrentString {get; set;}

Some XML comments provide a lot more than a simple summary. For example, when you create a method that has input and output values, the XML comment reflects this fact, as shown here:

/// <summary>
/// Performs a specific string change.
/// </summary>
/// <param name="Value">
/// The string you want to change.
/// </param>
/// <param name="Type">
/// The type of change you want to perform on the string.
/// </param>
/// <returns>
/// Provides the changed string as a return value.
/// </returns>
public string PerformChange(string Value, ChangeType Type)

Notice that this XML comment includes a lot more information. Each parameter has a <param> tag associated with it. The <param> tag includes the name attribute, which contains the parameter name. You type information about the parameter between the opening and closing tags. Any return value relies on the <returns> tag. All of this information appears within the XML file and IntelliSense makes use of it as the developer works with the method.

In many cases, you need to place XML comments within code blocks. For example, when working with an enum, you include an XML comment for each enumeration member, as shown here.

/// <summary>
/// Contains a list of the acceptable change types.
/// </summary>
[Category("Change Strings")]
[Description("Contains a list of the acceptable change types.")]
[DefaultValue(ChangeType.Lowercase)]
public enum ChangeType
{
   /// <summary>
   /// Reverses the order of the string elements.
   /// </summary>
   Reverse,

   ... Other Members ...

   /// <summary>
   /// Moves the characters around so they appear in a
   /// random order.
   /// </summary>
   Randomize
}

In this case, each of the members has a separate XML comment that appears when you work with that member in the editor. You see the comments when you work with the enumeration in the editor, so it’s important to provide a comment that applies directly to that member.

After you add all of the XML comments you think you need, compile the application. What you receive as output is the XML file, along with any executable you’d normally create. The XML file appears in the same folder as the executable. Of course, there’s always that nagging question of whether you documented everything. Interestingly enough, Visual Studio tells you when you miss an important XML comment location. The omission appears in the Warnings tab of the Error List window, as shown in Figure 2, after you compile your application.

Figure 2: Checking for missing XML comments is easy—just ask Visual Studio to do it for you.

All you need to do to fix the problems with the XML comments is to double click the entries. The IDE takes you to the location of the missing comments in the code. Type the required XML comment and you’re ready to go. Your best clue that you don’t need an XML comment is that nothing happens when you type the starting \\\. Normally, when you type the triple slash, the IDE expands the comment to provide the required XML comment format.