Visual Studio Hacks

280

|

Chapter 8, Comments and Documentation

#69 Create Comments Faster

HACK

To enable the XML documentation file creation, you simply need to enter

the name of an XML file in the XML Documentation File property setting.

In Figure 8-1, I have entered the name XmlLib.xml. When the project is

built, Visual Studio will collect all of the XML comments and save them into

a single file named XmlLib.xml in the output directory of your project.

You can then use this .xml file to create any different type of documentation

[Hack #71].

HACK

#69

Create Comments Faster Hack #69

There are boring parts of the XML commenting process that you can

automate to make documentation more fun (and more likely to happen).

The problem with XML documentation comments is that somebody has to

write them. Even worse, often enough that someone is you. The Visual Stu-

dio IDE helps you by preparing an empty template when you type

/// in

front of a method, but in the end you still have to fill in the blanks.

Here’s an example. Imagine a method “AppendHtmlText” that is used to

append HTML text to some sort of buffer. This method has several over-

loads, and one of these overloads has a parameter of type “HtmlProvider”.

This is what Visual Studio will create when you start writing a new XML

documentation comment:

Figure 8-1. XML documentation file creation