One of the most common programming rules states that
documenting the source code is fundamental. This is of course the truth
but you have to think about the way source code is commented. Classical
comments are useful to explain what code does so that you can easily
remember how your code works if you need to retake it after a long time,
or they can help other developers to understand your code. But this is
not the only way of documenting code in .NET development. A
sophisticated environment such as Visual Studio offers the IntelliSense
technology that not only speeds up the way you write code but is also
shows instructions on how you use objects and members. This is possible
because of special kinds of comments that you can add to your code,
known as XML comments. Such comments allow writing the source code
documentation, explaining objects’ and members’ behavior, and also
providing descriptions and examples that can be shown up by
IntelliSense. But that is not all. Documenting code with XML comments is
particularly important if you develop reusable compiled libraries and
allow automating the process of building compiled documentation files
(such as .chm files) in a similar way to the MSDN documentation.
Understanding XML Documents
XML documents are not new in
Visual Basic 2010; they were first natively introduced with Visual Basic
2005. (In versions prior to 2005, XML comments were possible only via
third-party add-ins.) To understand why XML documents are an essential
topic, let’s take a look at a method invocation within the code editor. Figure 1 shows how IntelliSense appears on an uncommented method.
As you can see from Figure 1,
IntelliSense will correctly show up, but it will just show the method
name in a tooltip, without providing information on the method usage.
This is because the method was not commented with XML comments. Now take
a look at Figure 2 that shows how IntelliSense can provide information if the method was commented with XML comments.
The difference is evident.
Objects and members decorated with XML comments can provide full
explanation on their usage. This works in the code editor when
IntelliSense shows up with both source files and with compiled
executables. As mentioned at the beginning of this chapter, providing
XML comments is not only useful for IntelliSense but also when you
investigate objects in the Object Browser or for automating the process
of building compiled documentation for your libraries. Because of this,
adding XML comments to your code is something necessary in most cases,
especially if you develop reusable assemblies. In the next sections you
learn practical techniques for commenting the source code and getting
the most out of XML comments with Visual Basic.
Enabling XML Comments
When Visual Studio builds
the project output, it also creates an XML document storing all XML
comments. The XML document constitutes the actual code documentation. In
Visual Studio 2010 XML comments are enabled by default. Before reading
this chapter, ensure that XML comments are effectively enabled in your
project. To accomplish this, open My Project; select the Compile tab and, if it’s not checked, check the Generate XML Documentation file box. See Figure 3 for details.
Behind the scenes this requires the Visual Basic compiler to be launched by Visual Studio with the /doc
option, which makes the compiler also generate the XML documentation.
At this point you are ready to implement XML comments in your Visual
Basic code.
