If the C:Program FilesSandcastleData folder already contains a folder called Reflection, you need to delete that folder before running this batch file.
Launching Sandcastle
Once Sandcastle and the Sandcastle Help File Builder are downloaded and installed, launch the Sandcastle Help File Builder by selecting Start→Programs→Sandcastle Help File Builder→Sandcastle Help File Builder GUI.
You should see the window shown in Figure C-8 when the Sandcastle Help File Builder is launched.
Figure C-8
You can choose the type of documentation you want to generate from the HelpFileFormat drop-down listbox (see Figure C-9).
Click the Add button to add the assembly filename that you want to generate the documentation for (see Figure C-8). Once the assembly is selected (PointClass.dll in the bin/Debug folder, in this case), the XML document filename field is automatically selected (the same name as the assembly, but with an .xml extension).
You can add multiple projects into the same documentation by adding each assembly into the Sandcastle project.
Finally, set the ShowMissingNamespaces property to false.
Building and Viewing the Documentation
Once you are ready to build the documentation, click the Build the Help File button in the toolbar (see Figure C-10).
Figure C-10
You will be asked to save the project. Name it Documentation. Sandcastle will then generate the documentation. Afterward, you can view it by clicking the View Help File From Last Build button in the toolbar (see Figure C-11).
Figure C-11
Ensure that your Sandcastle project is saved in a folder whose name does not contain any special characters (such as #, ?, &, and +). If not, you won't be able to view the documentation properly.
Figure C-12 shows the generated documentation (the tree view on the left is shown with all the nodes expanded to reveal the full documentation).
Figure C-12
Let's just take a look at the documentation for the overloaded Length() method as illustrated in Figure C-13.
Figure C-13
As you can see, the text in the <overloads> element is used to provide a general description for the overloaded method, while the actual description for each overloaded method is detailed in the <summary> element.
Click on the first overloaded method of the Length() method to see the relationship between the documentation tag and the actual documentation, as shown in Figure C-14.
Figure C-14
If you had earlier checked the WebSite item in the HelpFileFormat property of the project, the documentation would look like Figure C-15.
Figure C-15
Distributing the Documentation
You specify the location of the generated documentation by setting the OutputPath property in the properties section in Sandcastle. By default, the documentation is always saved in the Help folder of the project's folder (see Figure C-16).
Figure C-16
The Help folder contains a single .chm file (Documentation) and a log file (LastBuild; assuming you only checked the HelpFile1x item in the HelpFileFormat property; see Figure C-17).
Figure C-17
To distribute the documentation with your class, you simply need to provide the file with the .chm extension.
If you checked the WebSite item in the HelpFileFormat property of the project, the Help folder will contain a list of files and folders. Simply load the Index.html file to view the documentation. To distribute your documentation, you need to distribute all the files and folders within the Help folder.
