public double Length(Point pt) {
return Math.Sqrt(
Math.Pow(this.x - pt.x, 2) + Math.Pow(this.y - pt.y, 2));
}
}
}
Take a look at the documentation you have done for one of the overloaded Length() methods:
//---overloaded methods---
/// <overloads>
/// Calculates the distance between two points
/// </overloads>
/// <summary>
/// Calculates the distance of a point from the origin
/// </summary>
/// <returns>T he distance between the current point and the origin
/// </returns>
/// <example> This sample shows how to call the <c>length()</c>
/// method
/// <code>
/// Point ptA = new Point(3, 4);
/// double distance = ptA.Length();
/// </code>
/// </example>
You will notice that there is a new element — <overloads> — that is not in the list specified in the MSDN documentation. The <overloads> element is used to give a general description for methods that are overloaded. You will see the effect of this element later when you generate the documentation using the third-party tool. You only need to specify the <overloads> element on one (any one will do) of the overloaded methods.
You can also include code samples in your documentation using the <example> tag. To format a word (or sentence) as code, use the <c> tag. For multiple lines of code, use the <code> tag.
Because the XML comments that you add to your code may make reading difficult, you can hide the comments by clicking the minus sign (–) on the left of the code window. To reveal the XML documentation, click the plus sign (+) as shown in Figure C-4.
Figure C-4
Once you have inserted the XML comments in your code, right-click the project name in Solution Explorer and select Properties. Select the Build tab and check the XML Documentation File checkbox (see Figure C-5). This indicates to the compiler that after the project is compiled, it should consolidate all the XML comments into an XML documentation file. By default, the XML document will be saved to the bin/Debug folder of your project.
Figure C-5
Build the project by right-clicking the project name in Solution Explorer and then selecting Build. The XML documentation file is now located in the bin/Debug folder of your project, together with the PointClass.dll library. Figure C-6 shows what the XML file looks like.
Figure C-6
Generating the Documentation
With the XML documentation file generated, you have two options in terms of using the documentation:
□ Write your own XSLT transformation style sheets to transform the XML document into a readable format such as HTML, PDF, and so on.
□ Use a third-party tool to automatically parse the XML documentation into the various documentation formats it supports.
The second option is the easier. For this purpose, you can use the free Sandcastle tool that generates documentation in several different formats, including the MSDN-style HTML Help format (.chm), the Visual Studio .NET Help format (HTML Help 2), and MSDN-Online style Web pages.
Downloading and Installing Sandcastle
To use Sandcastle to generate your documentation, first ensure that you have HTML Help Workshop by checking for the existence of the following folder: C:Program FilesHTML Help Workshop.
If the folder is not there or does not contain hhc.exe, you can search for it and download it from Microsoft's web site.
Next, download Sandcastle from http://codeplex.com/Sandcastle.
By itself, Sandcastle is a command-line tool and all interaction with it is via the command line. To make your life easier, you can download the Sandcastle Help File Builder, a graphical user interface (GUI) tool that makes Sandcastle easy to use.
Once Sandcastle is downloaded and installed, download the Sandcastle Help File Builder from http://codeplex.com/SHFB.
Download the Presentation File Patches from the Sandcastle Styles Project site (http://codeplex.com/SandcastleStyles). Extract the Presentation folder and overwrite the Presentation folder in the Sandcastle folder with it (in C:Program FilesSandcastle; see Figure C-7).
Figure C-7
Due to the continual development of the Sandcastle project, these screen shots may differ from what you actually see on your screen.
Finally, you should run the BuildReflectionData.bat batch file (located in C: Program FilesEWSoftwareSandcastle Help File Builder) to build the reflection data for the version of the .NET runtime you are using.
