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!
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:
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
iButtons in the script and you will see basic IntelliSense Quick Info for those items. The Quick Info for
ReportAndPrompt is shown below.
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.
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
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
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 "
>", and "
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 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.
''' <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
= sign, a member list will display with all the known constants that are part of the
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.