Visual Studio Hacks [Electronic resources] نسخه متنی

8.1. Hacks 68-72

A
big part of developing a high-quality application is properly
documenting that application. Documentation starts during the design
process with your design documents (UML diagrams, use cases, stories,
etc.) and then continues during the process of creating that
application. A large part of documenting an application you are
developing is correctly commenting it. Good comments are even more
important with the .NET Framework because you can generate
documentation based on your comments.

Two types of
comments
can be used with the .NET Framework. The most common type is




line comments (whenever you use
// with C# or ' with VB.NET to
mark a line as a comment). This type of comment is usually used to
explain what the current or next line of code is doing. While these
types of comments are very valuable (and I would hate to try and
understand an application with none of these), the focus of this
chapter will be on another type of comment,
XML
comments. These comments document a class or method using a piece of
XML. The comments can then be used for a number of different things,
not least of which is generating API documentation for your
application. Here is an example of XML comments applied to a C#
method:

/// <summary>
/// This method accepts a string and then 
/// displays that string using a message box
/// </summary>
/// <param name="textToDisplay">The string to display</param>
private void HelloWorld(string textToDisplay)
{
MessageBox.Show(textToDisplay);
}

To use XML comments with VB.NET, you have to do a little more work
[Hack #70] .

The hacks in this chapter will cover how to get the most out of XML
comments, how to create comments faster using an add-in, how to
create documentation from your comments, how to use XML comments with
VB.NET, and how to integrate your own documentation into Visual
Studio.