Test Design StudioGo to Previous Topic: CreateObject Member ListGo to Next Topic: Object Repository IntelliSense

Working with XML Comments

Introducing XML Comments

Now that you have seen some of the IntelliSense capabilities of Test Design Studio, we will explore how you can apply specially formatted XML Comments to your own classes and functions to document their responsibilities and bring IntelliSense to life. This is where Test Design Studio sets itself apart from other editors. It is easy to provide rich information for known VBScript functions like StrComp, but detailed information is simply not available for user-defined code. Test Design Studio employs special XML-formatted comments to decorate your code and light up IntelliSense for all code!

Automatic Support Without XML Comments

Without XML Comments, we still know basic information about language elements that will provide core IntelliSense. Functions, for instance, have a clear function name and zero or more named parameters. With this basic information, we can provide function names in member lists and basic parameter information for the function call. What we cannot do, however, is determine key information like the purpose of parameters or the type of data they are expected to hold. XML Comments will solve this problem, but let's first explore automatic functionality without the use of XML comments.

Beginning a new example, we are going to add a basic declaration of a method. Delete all the text from your open script and replace it with the following text:

[VBScript] - Copy Code
Public Sub ReportAndPrompt(ByVal iStatus, ByVal sStep, ByVal sDetails)

  Dim iButtons

  ' Send details to the log
  Reporter.ReportEvent iStatus, sStep, sDetails

  ' Display message to the user
  If iStatus = micFail Then
    iButtons = vbOKOnly Or vbError
  ElseIf iStatus = micWarning Then
    iButtons = vbOKOnly Or vbExclamation
  Else
    iButtons = vbOKOnly Or vbInformation
  End If
  MsgBox sDetails, iButtons, sStep

End Sub

Use the mouse to hover over the names ReportAndPrompt, iStatus, sStep, sDetails, and iButtons in the script and you will see basic IntelliSense Quick Info for those items. The Quick Info for ReportAndPrompt is shown below.

Unlike the StrComp function used in the previous examples, the sub ReportAndPrompt does not have a detailed description. This is because the StrComp function is a built-in function that has already been documented, but user-defined functions and subs like ReportAndPrompt require the entry of XML comments to define the sub.

Note:   Since VBScript is not a strongly typed language, variables can hold any type of data. For this reason, VBScript variables default to the type Variant. When a variable is expected to hold a specific type of data, we can specify that using XML comments to make our documentation more valuable.

XML Comments to the Rescue

We will now enter the XML comments to describe the ReportAndPrompt sub and observe the changes in IntelliSense.

Insert a blank line above the sub declaration and place the caret at the beginning of that line. Then type three comment characters without any spaces in between (i.e. '''). These three comment characters are used to designate special XML-formatted comments. Typing these comment characters immediately before an item like our sub declaration will result in the automatic generation of a skeleton of XML comments for that item. The following shows the result of the automatic XML comments for our sub declaration:

This code skeleton makes it easy for us to provide a summary for the function, a summary of each parameter, and the type of data expected for each parameter.

Complete the XML comments as shown below. This includes setting the sub summary in the summary tag, setting the type of each parameter, and setting the summary of each parameter within the param tag. This provides Test Design Studio with rich information about the ReportAndPrompt function. After completing the XML comments, use the mouse to hover over the names ReportAndPrompt, iStatus, sStep, sDetails, and iButtons to see the updated Quick Info for those items like the ReportAndPrompt sub shown below:

Note:    The XML Comment data may be formatted in any way as long as XML formatting rules are still observed. Specifically remember that "<", ">", and "&" are just a few special characters in XML that must be typed as "&lt;", "&gt;", and "&amp;" respectively.

XML comments are the life blood of the rich editing experience you receive with Test Design Studio. The data entered in XML comments will show up in the IntelliSense Member Lists, Parameter Info, and Quick Info descriptions as well as be displayed for relevant entries within the Object Browser tool window and any generated documentation.

XML Comments on Variables

XML comments are not only for methods. You can also use XML Comments to describe the variable iButtons that is declared within the body of the sub. Insert a blank line above the line Dim iButtons and type the three magical comment characters; '''. A more basic XML comment skeleton is inserted to describe the value of the variable. To avoid the variable from being seen as a Variant type, set the type attribute of the value tag to MessageBoxButtons. Unlike String, Integer, DateTime, or Boolean, this is a special type known as an Enum that defines a list of values that are valid for the variable. Specifically, this variable holds data of the type Integer, but the MessageBoxButtons Enum is a specific list of Integer constants that are expected. The example below also shows how you can provide summary information for a variable.

[VBScript] - Copy Code
''' <summary>Stores the Button and Icons to display in the MessageBox.</summary>
''' <value type="MessageBoxButtons"/>
Dim iButtons

As a bonus when working with Enum-based types, you will see a member list displayed when assigning a value to that variable. On any blank line in body of the sub (after the iButtons variable is declared), type the text iButtons = . When you type the space after the = sign, a member list will display with all the known constants that are part of the MessageBoxButtons enum!

Learn More

We are only introducing the basics of how XML Comments can bring your code to life. Click here for details on how to use XML Comments and the available tags, including advanced features like defining your own Enum lists.

Note:    XML Comments use a different syntax highlighting color than standard comments when viewed in Test Design Studio. Unified Functional Testing will continue to recognize them as standard comments with the same highlighting color.
Tip:    Use the Object Browser to browse the available Enum's for VBScript, Unified Functional Testing, and other languages.

You may now close the VBScript document you have been working on.