Test Design StudioGo to Previous Topic: XML CommentsGo to Next Topic: Using the 'type' Attribute

Documenting a Function/Sub

Documenting the functions in a function library is one of the most important uses of XML comments in Test Design Studio. You are able to provide details about almost every aspect of a function. The most common tags used when defining a function are 'summary', 'param', and 'returns'. Other stand-alone tags are also supported, but this topic will cover the tags most important when defining a function or those tags specific to a function. The following shows a sample XML comment block for a function.

[VBScript] - Copy Code
''' <summary>
''' This is the summary of my function.
''' </summary>
''' <param name="Window" type="String"></param>
''' <param name="Count" type="Integer"></param>
''' <returns type="Boolean">Returns True if successful, otherwise False</returns>
Public Function TestFunction(Window, Count)

End Function
[JScript] - Copy Code
/// <summary>
/// This is the summary of my function.
/// </summary>
/// <param name="window" type="string"></param>
/// <param name="count" type="int"></param>
/// <returns type="bool">Returns True if successful, otherwise False</returns>
function testFunction(window, count)
{
}
Note:   While referring to functions, these tags are usable on a VBScript 'Sub' routine unless otherwise noted.

Summary

As with all elements, the 'summary' tags provides a general overview about the function. Since the summary is used to display IntelliSense, use care not to make the summary too long or complex.

Parameters

The 'param' tag is used to define the parameter whose name is specified in the 'name' attribute of that tag. The 'name' attribute must exactly match the name of a parameter in the function declaration. The 'type' attribute of the 'param' tag is optional and can be used to indicate the expected type of the variable (i.e. String, Integer, Boolean, etc.). The inner text of the 'param' tag describes the purpose of the parameter. The optional 'paramlist' attribute is used to tie this parameter to a parameter list (see 'paramlist' tag below).

The following sample describes a parameter accepting an Integer value:

[VBScript] - Copy Code
''' <param name="param_name" type="Integer">This is an integer parameter</param>
[JScript] - Copy Code
/// <param name="param_name" type="int">This is an integer parameter</param>

Using a Parameter List

The purpose of a parameter list is to specify a list of expected values for a parameter. Defining and using a parameter list is similar to defining an enum. The main difference is that enums are defined in file-level comments and are typically used by more than one function. A parameter list can be used to define a list of values unique to a given function or any other list for which you do not want to create an enum.

The 'paramlist' tag is used to define a list of values that are expected for a parameter. The 'name' attribute of the 'paramlist' tag must correspond to the 'paramlist' attribute of the relevant 'param' tag to associate the list to the parameter. The following examples show how a parameter is tied to a parameter list:

[VBScript] - Copy Code
''' <param name="param1" type="String" paramlist="listname" />
''' <paramlist name="listname">
''' <item>item1</item>
''' </paramlist>
[JScript] - Copy Code
/// <param name="param1" type="string" paramlist="listname" />
/// <paramlist name="listname">
/// <item>item1</item>
/// </paramlist>
The 'item' tag is nested within the 'paramlist' tag to define the individual items included in the list. There are two methods for populating the item tag:

Inner Text Method

You can directly enter the text of the list item using the inner text of the 'item' tag.
[VBScript] - Copy Code
''' <paramlist name="colors">
''' <item>red</item>
''' <item>yellow</item>
''' <item>blue</item>
''' </paramlist>
[JScript] - Copy Code
/// <paramlist name="colors">
/// <item>red</item>
/// <item>yellow</item>
/// <item>blue</item>
/// </paramlist>

Sub-Tag Method

You can nest the 'text' and 'description' tags within the 'item' tag to define the list item as well as a description for that item. The description will appear in IntelliSense and Documentation.
[VBScript] - Copy Code
''' <paramlist name="colors">
''' <item><text>red</text><description>The color Red</description></item>
''' <item><text>yellow</text><description>The color Yellow</description></item>
''' <item><text>blue</text><description>The color Blue</description></item>
''' </paramlist>
[JScript] - Copy Code
/// <paramlist name="colors">
/// <item><text>red</text><description>The color Red</description></item>
/// <item><text>yellow</text><description>The color Yellow</description></item>
/// <item><text>blue</text><description>The color Blue</description></item>
/// </paramlist>
Tip:   All 'item' tags within the 'paramlist' tag do not have to use the same method (i.e. you can mix the 'Inner Text' and 'Sub-Tag' methods as necessary to only apply descriptions to certain items.

String Values

The text of the item will be treated exactly as it is entered, so be sure to enter string values within quotation marks.
[VBScript] - Copy Code
''' <paramlist name="listname">
''' <item>"item1"</item>
''' </paramlist>
[JScript] - Copy Code
/// <paramlist name="listname">
/// <item>"item1"</item>
/// </paramlist>

Setting Return Values

Knowing what a function returns can often be as important as knowing the type of data to provide in an argument list.

Note:   These tags have no relevance when used on a VBScript 'Sub' since they do not return a meaningful value.

General Return Information

The 'returns' tag is primarily used to define what is returned from a function. The 'type' attribute describes the type of the return value (i.e. String, Integer, Boolean, etc.). The inner text is used to describe the value being returned.

[VBScript] - Copy Code
''' <returns type="Boolean">Returns True if successful, otherwise False.</returns>
[JScript] - Copy Code
/// <returns type="int">Returns True if successful, otherwise False.</returns>

Defining Specific Values Returned

The 'returnvalue' tag is used to define a specific value that may be returned from a function. This tag expects one of two attributes:
AttributeDescription
name Use the 'name' attribute to define the specific value being returned. The inner text of the 'returnvalue' tag is then used to further describe that item. You may optionally use the 'type' attribute to define the type of value being returned.
[VBScript] - Copy Code
''' <returnvalue name="0" type="Integer">Indicates a successful operation</returnvalue>
[JScript] - Copy Code
/// <returnvalue name="0" type="int">Indicates a successful operation</returnvalue>
cref Use the 'cref' attribute to indicate a reference to another item that may be returned from the function. The details of the referenced item will be used to describe the return value, so no inner text needs to be defined.
  • Reference a specific constant value that may be returned.
  • Reference a function whose return values may be returned (i.e. import the same return values from the referenced function).
  • Reference an enum list of values that may be returned.
[VBScript] - Copy Code
''' <returnvalue cref="micPass"/>
[JScript] - Copy Code
/// <returnvalue cref="E_OK"/>

Overloads for a Function

When certain parameters to a function are optional, this creates multiple ways that the same function can be called. Test Design Studio refers to this concept as an "overloaded" function, and you have the ability to define, using XML comments, the additional ways a function may be called.

You begin defining an overload using the 'overload' tag. Within that tag, you then use the 'param' tag to specify which parameters are part of that overload. The following example shows how an overload can be specified to indicate that the function can be called with a single parameter.

[JScript] - Copy Code
/// <summary>
/// This is the summary of my function.
/// </summary>
/// <param name="window" type="string">Base description of 'window' parameter.</param>
/// <param name="count" type="int">Base description of 'count' parameter.</param>
/// <returns type="int">Returns E_OK if successful, otherwise an error occurred</returns>
/// <overload>
///   <summary>Optional new summary of function used for this overload.</summary>
///   <param name="window">Optional new description for 'window' parameter used for this overload.</param>
///   <returns type="bool">Optional new return description and/or value type for this overload.</returns>
/// </overload>
function testFunction(window, count)
{
}
Note:   Since VBScript does not allow optional arguments, the VBScript sample is now shown. Test Design Studio does, however, still support this concept for VBScript even if it is not practical.

Summary

When defining the overload, you may include an optional 'summary' tag if you want the summary of that function to appear differently for that specific overload. When not specified, the base summary will be used.

Parameters

The 'param' tag is used to indicate which parameters are populated for this overload. The 'name' attribute must exactly match the name of the parameter in the function declaration. You may optionally use the 'type' attribute to change the expected value type of the parameter for that overload. You may also optionally define a new summary for that parameter. If either of these optional elements are not included, the base value will be used.

Returns

The 'returns' tag may be used to optionally change the return value type or description of what the function returns.

Other Useful Tags

In addition to the tags defined above, additional tags that are also useful for functions include:

See the XML Comments page for details about the use of these common tags.