Visual Studio Hacks

272

|

Chapter 8, Comments and Documentation

#68 Master C# XML Comments

HACK

The hacks in this chapter will cover how to get the most out of XML com-

ments, how to create comments faster using an add-in, how to create docu-

mentation from your comments, how to use XML comments with VB.NET,

and how to integrate your own documentation into Visual Studio.

HACK

#68

Master C# XML Comments Hack #68

Comment your code with a sprinkling of XML, and give IntelliSense and

documentation tools plenty of grist for their mills.

XML comments are a compelling addition to any project. Using XML com-

ments, you can document all of your public classes, methods, and enumera-

tions while you program. The basics of XML comments are very simple—

precede your comments with

///, and Visual Studio will add a basic sum-

mary and an element for each of the parameters on your method. You can

then enter the summary and parameter descriptions. But there is much more

to XML comments; there are 20 different tags that can be used in XML com-

ments. In this hack, you are going to learn how to use all of these tags to cre-

ate better documentation.

To insert XML comments, simply type

/// on a line preceding a class, inter-

face, method, field, or property declaration. As soon as you type these char-

acters, IntelliSense will give you a skeletal XML comment with an empty

<summary> element:

/// <summary>

///

/// </summary>

public void Foo( )

Technically ...