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 50.1 shows how IntelliSense appears on an uncommented method.

Figure 50.1 Uncommented members make IntelliSense unable to display useful information.

As you can see from Figure 50.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 50.2 that shows how IntelliSense can provide information if the method was commented with XML comments.

Figure 50.2 Commented members are well described when IntelliSense shows up in the code editor.

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.