Implementing XML Comments

XML comments have a double purpose. The first one is enabling additional help within IntelliSense when you write code. The second one is generating an XML file storing information that can be built into a compiled documentation file, such as the .Chm format that also allows navigation between documented items. In this section you learn to implement XML comments understanding the various tags and why they are important; although in some cases it might not seem to be. Before implementing comments, create a new Console application and implement a Person class as follows:

The Person class will be the base for our experiments. You implement an XML comment by typing three apostrophes. The Visual Studio code editor adds a comment skeleton to your code that first looks like the following example:

As you can see, these comments have typical XML structure according to the <tag> </tag> syntax. The summary XML tag enables describing what an object (or member) does. The description will be also available within IntelliSense. The remarks tag enables providing additional information on what you already specified in the summary, and the information will also be displayed within the Object Browser (but not within IntelliSense). The returns tag specifies the type returned by the member (being a method or a property); in case the member is a method that does not return a value, Visual Studio will not add the returns tag. For a better understanding, populate comments as follows:

Now go to the Main method in your Console application, and write the following code that instantiates and populates the Person class:

When typing code, you notice how IntelliSense provides information on the GetFullName method according to the XML comment’s content. This is represented in Figure 50.4.

Figure 50.4 IntelliSense shows the information provided by the XML comments.

As you can see, IntelliSense basically shows the content of the summary tag whereas it does not show the content of the returns and remarks tags. This makes sense in that IntelliSense’s tooltips are the fastest way for getting help. If you instead open the Object Browser on the Person class, you get a result that looks similar to Figure 50.5.

Figure 50.5 The Object Browser shows information provided by XML comments.

You obtain the same detailed information if you build a compiled documentation file, as described later in this chapter. The one shown before is the most basic implementation of XML comments. By the way, this great Visual Basic feature allows defining complex documentation over your code, which can be particularly useful also due to the integration with the Visual Studio environment.