9.3. Using XML Comments
Once you have the XML comments inline with your code, you'll most likely want to generate an XML file containing the documentation. In Visual Basic this setting is on by default, with an output path and filename specified with default values. However, C# has the option turned off as its default behavior, so if you want documentation you'll need to turn it on manually.
To ensure that your documentation is being generated where you require, open the property pages for the project through the Solution Explorer's right-click context menu. Locate the project for which you want documentation, right-click its entry in the Solution Explorer, and select Properties. Alternatively, in Visual Basic you can simply double-click the My Project entry in the Solution Explorer.
The XML documentation options are located in the Build section (see Figure 9-2). Below the general build options is an Output section that contains a checkbox that enables XML-documentation file generation. When this checkbox is enabled, the text field next to it becomes available for you to specify the filename for the XML file that will be generated.
Figure 9.2. Figure 9-2
Once you've saved these options, the next time you perform a build, Visual Studio will add the /doc compiler option to the process so that the XML documentation is generated as specified.
The XML file that is generated will contain a full XML document that you can apply XSL transformations against, or process through another application using the XML Document Object Model. All references to exceptions, parameters, methods, and other "see also" links will be included as fully addressed information, including namespace, application, and class data. Later in this chapter you see how you can make use of this XML file to produce professional-looking documentation using Sandcastle.
9.3.1. IntelliSense Information
The other useful advantage of using XML comments is how Visual Studio 2008 consumes them in its own IntelliSense engine. As soon as you define the documentation tags that Visual Studio understands, it will generate the information into its IntelliSense, which means you can refer to the information elsewhere in your code.
IntelliSense can be accessed in two ways. If the member referred to is within the same project or is in another project within the same solution, you can access the information without having to build or generate the XML file. However, you can still take advantage of IntelliSense even when the project is external to your current application solution.
The trick is to ensure that when the XML file is generated by the build process, it has the same name as the .NET assembly being built. For example, if the compiled output is myApplication.exe, then the associated XML file should be named myApplication.xml. In addition, this generated XML file should be in the same folder as the compiled assembly so that Visual Studio can locate it.