Remarks for the payment mode enumerator in Visual C#

Generating QR in Visual C# Remarks for the payment mode enumerator

<summary> Payment mode </summary> <remarks> <div class="tablediv"> <table> <tr valign="top"> <th>Term</th> <th>Description</th> <th>Example</th> </tr> <tr valign="top"> <td>In advance</td> <td>Begin mode is typical for leasing</td> <td><c>Calc.Math.Finance.Mode.BeginMode</c></td> </tr> <tr valign="top"> <td>In arrears</td> <td>End mode is typical for loans and mortgages</td> <td><c>Calc.Math.Finance.Mode.EndMode</c></td> </tr> </table> </div> </remarks>

As you can see, you can declare HTML-style tables inside the XML documentation. That s nice, you say. It s a lot of XML code in my source files. IntelliSense is handy in Visual Studio, but that s hardly real documentation. But what if we tell you that you can generate from the XML documentation like that shown in figure 9.3 You can create this MSDN-style documentation using Sandcastle.

Sandcastle is a set of free tools from Microsoft that you can use to transform XML documentation into a formatted document. It contains a bunch of command-line programs that you can automate to create documentation, but this technique would take too long to discuss here. There s a much quicker and more pleasant way: you can use Sandcastle Help File Builder (SHFB), which is also free. Both are available

from CodePlex: Sandcastle at www.codeplex.com/Sandcastle and SHFB at http:// shfb.codeplex.com/. Install both on your development machine. Before you start, make sure Visual Studio is extracting all of your XML documentation into a single XML file. You can check this XML Documentation File setting in your project properties (see figure 9.4.).

Figure 9.4 Select the XML Documentation File check box in your project properties to make Visual Studio extract the XML documentation into a given XML file.

Visual Studio 2010 is so clever that it makes this change for you as soon you add the first /// comment to a project (provided you ve selected the option Tools > Options > Text Editor > C# > Advanced > Generate XML Documentation Comment for ///). In earlier versions, you ll have to select the option manually.

Start SHFB, which is essentially a GUI for Sandcastle. Using this tool, you ll create a project file with all the necessary settings. At the end, you ll take this file for a ride with MSBuild. You want to be able to create documentation even on a machine that doesn t have Sandcastle and SHFB installed. So take both installed tools and copy them to the tools directory in your project folder: put Sandcastle in tools\Sandcastle and SHFB in tools\SHFB. Remember to put in the tools directory only what s needed don t clutter the project directory with unnecessary files. What you need depends on what template you ll use to format the documentation. You can delete all the readme and help files you don t need them in the repository. Start SHFB by running tools\SHFB\SandcastleBuilderGUI.exe. Add the compiled DLL and accompanying XML file to Documentation Sources in Project Explorer. Specify the obvious project properties, such as FooterText, HeaderText, HelpTitle, CopyrightText, and so on. Then get to the not-so-obvious but important properties that are important from the CI point of view; see figure 9.5 for details.

If you re building using the Debug/Release configuration, go to the DLL and XML properties and replace the configuration name with the $(Configuration) MSBuild variable. You can use the MSBuild variables because the SHFB project files are in fact MSBuild scripts. One important project property you have to set is SandcastlePath: set it to $(MSBuildProjectDirectory)\tools\Sandcastle\. It ll use the MSBuild predefined variable to build an absolute path to the Sandcastle binaries. You need to set one more property in order for the documentation process to work on a machine that doesn t have Sandcastle installed. In Project Properties, locate UserDefinedProperties, and click the button. Figure 9.6 shows the dialog box that opens. Thanks to the SHFBROOT variable, MSBuild tasks can locate the SHFB installation for any necessary files. There s no way to document the namespace using the XML documentation. Even if you use the <summary> tag on a namespace, it ll be ignored by the compiler, and it won t be added to the XML file. You can close this gap by documenting the namespace in the SHFB GUI. In Project Properties, locate the Namespace Summaries property, and open it. Figure 9.7 shows the dialog box in which you can add the summaries. You can browse the other properties, such as HelpFileFormat. By default, you re generating an HtmlHelp file. But you can change it to a website if you want to deploy the documentation to a web server for immediate viewing. And look at the PresentationStyle property: you can dress up your documentation in various ways. Visibility lets you choose which filters to use on the documentation elements.