As discussed earlier, the first step to generating documentation for your source code is configuring your project to export an XML documentation file. This file will be used later by NDoc to produce our documentation files.

Start by bringing up the project properties window; the easiest way to do this is by right-clicking on your project in the solution explorer and selecting Properties. After you navigate to the Build tab, you should see the dialog shown in Figure 11.1.

Figure 11.1. Build configuration properties for a project.

You will notice that there is a property called XML documentation file under the Output property group; that is the path that must be set for the documentation file to be generated at. This path is relative to the project directory, and standards suggest that the file name match the name of the assembly. For example, NDocExample.dll should have an XML documentation file named NDocExample.xml.

Once a valid file path is specified, when the project is compiled, an XML file will be generated that contains all the XML comment tags that were embedded in the source code.

You may have some projects that will be compiled from the command line, and the way to generate the XML documentation file in such a situation is by using the /doc flag.

csc /doc:NDocExample.xml NDocExample.cs

In either situation, command line or through an IDE, the /doc compiler switch will be ignored in a compilation that uses the /incremental build switch. Therefore, you should use the /incremental- switch to disable the incremental build and ensure that your XML documentation file remains up-to-date.

After your project is configured to output an XML documentation file, any comments that are suggested to be included will not prevent compilation, assuming you do not have warnings set to errors, but will instead show up as a warning in the task list. You can simply double-click on the warning in the task list to jump to the location where a comment should be added, much as any other error or warning can be navigated to.

Figure 11.2 shows the source code location where the comment should be inserted.

Figure 11.2. Example of a source code location that should be commented.

Figure 11.3 shows a comment missing from the constructor of MainForm, and suggests that it be added for standards compliance.

Figure 11.3. Missing comment warning in the Visual Studio C#.NET task list.

An extremely useful feature that improves documentation productivity is a macro that inserts basic commenting tags for a particular method or class. Simply place the text insertion pointer on the line above the method or class header in question and press the / (forward slash) key three times. A summary tag block is inserted, along with all the parameter tags for the method, if applicable. Additional tags can be added to the basic blocks that were inserted, but they have to be added manually.

There are quite a few supported XML tags and tag attributes that can be used for different purposes when documenting your code; those tags are described in Table 11.1, along with instructions for when they should be used.

Keep in mind that in order to generate correct XML, the compiler must be given correct documentation comments. Additionally, the compiler will generate a warning and embed an error message in the documentation file if it is given XML that is not well-formed. By well-formed XML, I mean XML that follows the rules listed in the W3C Recommendation for XML 1.0.

A list of the standard tags available for inline documentation are presented in Table 11.1.

The commenting structure is fairly loose and flexible, but you will notice that any suggested comments to include will appear as warnings in your task list now that your project is configured for commenting.

Keep in mind that since the compiler recognizes /// as a comment line when parsing source code for embedded XML, the following documentation will be rejected by the compiler:

/// <summary>
///
// </summary>
Public void FooBar() {}

Obviously, all documentation comments must be associated with a valid code construct, otherwise they will be ignored. Valid code constructs are a class, struct, enum, property, field, method, delegate, indexer, or event.

Some documentation tags are further defined through the use of XML attributes. The tag attributes used by inline documentation are presented in Table 11.2.

In order to illustrate the entire process of documenting source code, we will define and discuss a simple example in a linear fashion.

We will start by defining a simple method called SaveApplicationSettings that will accept a string parameter and not return anything. This method won’t do anything in terms of functionality, but it will show how to properly document a code construct.

/// <summary>
/// Saves the application settings to a text file named by
/// the fileName property, and saved in isolated storage.
/// </summary>
/// <param name="fileName">
/// The name of the file to store the application settings in.
/// </param>
/// <example>
/// The following code shows how to properly call this method.
/// <code>
/// SaveApplicationSettings("MyApplication.xml");
/// </code>
/// </example>
/// <permission cref="System.Security.PermissionSet">
/// This method can be accessed by everyone
/// </permission>
public void SaveApplicationSettings(string fileName)
{
    MessageBox.Show("This is where the settings would actually be saved");
}

As you can see in the above code example, we have documented the source code for the SaveApplicationSettings method, and now that we have done so, it is available for IntelliSense. Now whenever you start typing out the name of the method, IntelliSense will fire up and give you information about the method and the parameters it expects. This is illustrated in Figure 11.4.

Figure 11.4. Example of on-the-fly IntelliSense documentation.

Aside from on-the-fly IntelliSense, you can also mouse over a documented method or type and see the documentation overview for it. This is depicted in Figure 11.5.

Figure 11.5. Example of IntelliSense type overview.

IntelliSense information is a handy tool, but using XML documentation for IntelliSense alone is a waste compared to the wonderful documentation that can be generated from the XML documentation file. There are two main ways to generate your documentation, but the NDoc approach will be the evangelized method in this chapter.

The first method, and the one this chapter will not cover, is the built-in documentation tool in Visual Studio .NET. Under the Tools menu is an option titled Build Comment Web Pages..., which will produce help files in the Visual Studio .NET format. While this method works and is convenient because of the IDE integration, NDoc produces much better documentation in a variety of formats.

For starters, launch the NDoc application and select the New from Visual Studio Solution option from the toolbar at the top of the window, as shown in Figure 11.6. At this stage, we must let NDoc know which assemblies have commenting enabled and should have corresponding documentation generated for them. This step could be done manually, although referencing the assemblies automatically from your project solution is much easier and faster.

Figure 11.6. Toolbar option to import assemblies.

Selecting the toolbar option should bring up a dialog that asks you to select the solution configuration of the project to use. I typically use debug mode, but it generally doesn’t matter when you stick with default solution configurations. This dialog should look like the one shown in Figure 11.7.

Figure 11.7. Dialog asking to select the solution configuration to use.

After the appropriate solution configuration to use has been selected, the NDoc window should populate with all the referenced assemblies for the solution. There are a number of formatting and configuration settings that can be modified for an NDoc project, but for the most part, we will use the default values for the purpose of this discussion. You should end up with a dialog similar to the one shown in Figure 11.8. The final step (yes, it is that easy) is to build the documentation by clicking on the Build Documentation button in the toolbar, or by using the Ctrl+Shift+B shortcut.

Figure 11.8. Main NDoc interface showing the loaded assemblies and project properties.

Once the Build Documentation button is clicked, the XML documentation file will be processed and an MSDN-style .chm file will be generated at the location specified by the OutputDirectory property in the NDoc solution. Keep in mind that you can switch the documenter plugin if you do not want MSDN-style documentation and would prefer an alternative format. The MSDN-style .chm documentation will look something like Figure 11.9.

Figure 11.9. Example MSDN-style .chm documentation created with Ndoc.

Source code documentation has always been regarded as a hassle to create, yet it is important to promote maintainability. In this chapter, we saw another situation where the .NET platform improved workflow productivity, specifically in terms of generating source code documentation. Developers are generally conscientious about source code commenting, and luckily most organizations have coding standards that enforce a certain level of consistency, but commenting your source code and producing aesthetic documentation are two different challenges in themselves.

This chapter described a great way to transition from commented source code to deployment-quality documentation using a core architecture primitive in the .NET platform.