Test Design StudioGo to Previous Topic: Outlining (Code Folding)Go to Next Topic: Documenting a Function/Sub

XML Comments

XML Comments are used to describe language items within context-sensitive files. The details provided through XML Comments appear in the Object Browser, IntelliSense, and generated Documentation.

For VBScript language files (i.e. Unified Functional Testing and HPE Application Lifecycle Management Workflow), you can describe the following language elements:

Location and Formatting

XML Comments always appear on the line immediately before the item to which the comments apply (except file-level comments described below). An XML Comment will always begin with three comment characters (based on the language). Therefore, XML Comments in VBScript will always start with ''' while XML Comments in JScript will always start with ///. The actual content of the comments must be well-formed XML. This means the comments must follow the same rules as an XML document. All tags must be closed and properly nested.

Tip:   Any errors in XML formatting will be indicated by a red "squiggle" line and a corresponding entry will be shown in the Task List.

Sample Description
<tag/> A tag with no attributes and no inner text.
<tag>This is the inner text</tag> A tag with inner text and no attributes.
<tag attr="value" /> A tag with one attribute and no inner text.
<tag attr1="value1" attr2="value2" /> A tag with two attributes and no inner text.
<tag attr="value">This is the inner text</tag> A tag with inner text and one attribute.
Tip:   For additional details about XML Formatting and Syntax, visit this W3 Schools Tutorial.

File-Level Comments

You may also use XML Comments to describe an entire file. These comments must appear at the very beginning of a file to be properly recognized. To ensure that the comments are not mistakenly applied to an item declared in the file, you should place a minimum of three blank lines after the comments.

Entering Comments

The following sample code shows a function declaration:

[VBScript] - Copy Code
Public Function TestFunction(ByVal Param1, ByRef Param2) 
End Function
[JScript] - Copy Code
function testFunction(param1, param2) 
{
}

You can insert XML comments for this function by typing three comment characters on a blank line immediately before the declaration (i.e. for VBScript, you type '''). When you type the XML comment characters before a valid item, a skeleton is automatically inserted to describe the item you are commenting. The following will be displayed after typing three comment characters before the sample function declaration above:

[VBScript] - Copy Code
''' <summary>
''' 
''' </summary>
''' <param name="param1" type=""></param> 
''' <param name="param2" type=""></param>
''' <returns type=""/> 
Public Function TestFunction(ByVal Param1, ByRef Param2) 
End Function
[JScript] - Copy Code
/// <summary>
/// 
/// </summary>
/// <param name="param1" type=""></param> 
/// <param name="param2" type=""></param>
/// <returns type=""/> 
function testFunction(param1, param2) 
{ 
}

The skeleton includes the most common tags for the current item. Additional tags can be added as necessary. Typing the < character within XML Comments will typically show an IntelliSense Member List of applicable tags.

Stand-alone Tags

XML Tags are used to define attributes of a language item. Specific XML tags must be used to document the available attributes. These tags should never be nested or they will not be properly recognized. Unless otherwise noted, tags use the inner text of the tag to define the entry. Some tags will also use attributes or specific child tags. Standard tags are as follows:

TagDescription
summaryProvides basic information about the item you are describing. This entry is typically used when displaying IntelliSense, so use care not to make the summary too long or complex.
remarksProvides more detailed information about the item you are describing. Remarks are typically not seen when displaying IntelliSense, so the details of this tag can be long and complex.
valueThis tag is for properties, variables, constants, and enum items only. Uses the 'type' attribute to indicate the type of value represented by the item (i.e. String, Integer, Boolean, etc.). This tag does not use inner text. For functions, use the 'returns' tag instead. The following example would define a variable as a 'String':
[VBScript] - Copy Code
''' <value type="String"/>
Dim val
[JScript] - Copy Code
/// <value type="string"/>
var val;
returnsThis tag is for functions only. See Documenting a Function/Sub for details on the use of this tag.
paramThis tag is for functions only. See Documenting a Function/Sub for details on the use of this tag.
paramlistThis tag is for functions only. See Documenting a Function/Sub for details on the use of this tag.
returnvalueThis tag is for functions only. See Documenting a Function/Sub for details on the use of this tag.
seealsoCreate a cross-reference to the item specified by the 'cref' attribute. This tag does not use inner text.
exampleProvide information on the use of the item.
Note:   Example text defaults to standard formatting so that you may describe your example. Enclose the actual sample code within the 'code' tag to preserve formatting and syntax highlighting.
authorDefines the author of an item (i.e. user who created it).
datecreatedDefines the date upon which an item was created. The date can be formatted in any format recognized by system locale settings. The values 12/31/2012, 31/12/2012, and December 31, 2012 can all be used. When necessary, locale settings will determine which values correspond to month, day, year.
versionThis tag is for file-level comments only. Indicates the current version of the file.
sectionThis tag defines a custom section that will be created in a Documentation file. Use the 'title' attribute of the tag to specify the name of the section. The inner text will then be used to provide the content of the section.
browsable Indicates how the item will appear in IntelliSense Member Lists. Possible values:
  • always - (Default) The item will always appear in IntelliSense Member Lists.
  • never - The item will never appear in IntelliSense Member Lists.
  • advanced - The item will only appear in IntelliSense Member Lists when the 'Hide Advanced Members' option is not enabled. This option is set by opening the 'Options' dialog (select 'Tools -> Options' from the main menu) and locating 'Statement Completion' section within the 'Text Editor -> All Languages' option set.
list This tag is used to output lists of data. See Formatting Lists for details on the use of this tag.
enumThis tag is for file-level comments only. See Define an 'Enum' List for details on the use of this tag.
obsoleteThis tag will indicate that the corresponding item is obsolete and should no longer be used. Ideally, a summary for why the item is now obsolete should be provided in the inner text of the tag.
[VBScript] - Copy Code
''' <obsolete>This item is no longer valid.  Use 'xxx' instead.</obsolete>
Note:   For file types that support static language analysis, using an item marked obsolete will result in a warning.
suppressmessageThis tag will suppress certain errors and warnings generated by the static language analysis tool. Use this message to suppress issues for a particular area of code. Use the 'checkid' attribute to specify the specific ID of the message to suppress. Certain messages also require specification of the 'messageid' attribute when the same message could have applied to multiple items. Ideally, the reason for the suppression should be noted in the inner text of the tag.
[VBScript] - Copy Code
''' <suppressmessage checkid="CA00001">This warning is not valid here because...</suppressmessage>
Warning:   All warnings and errors deserve attention. Instead of disabling a particular static analysis message completely, suppress the individual areas where it does not apply after you have investigate the code.
Note:   This tag can only be used on language elements that "contain" other elements (i.e. file-level comments, class declarations, function/sub declarations, and property declarations)

In-line Tags

Within each of the stand-along tags above, you can nest additional tags to markup that item (i.e. adjust how the 'summary' information is displayed). The following example shows how the 'b' tag is used within the 'summary' tag to mark a portion of the summary for Bold text:

[VBScript] - Copy Code
''' <summary>
''' The last word of this sentence is <b>bolded</b>.
''' </summary>
[JScript] - Copy Code
/// <summary>
/// The last word of this sentence is <b>bolded</b>.
/// </summary>
TagDescription
bMark text as Bold.
emEmphasize text (typically Italics).
cMark text as in-line code.
codeMark text as multi-line code with formatting preserved and syntax highlighting (for recognized languages).
paraMark paragraphs.
paramref Indicate a direct reference to a named parameter (i.e. <paramref name="param1"/>).
see Indicate a link to an additional language item by name (i.e. <see cref="testfunction2"/>).

Additional Topics

Choose from one of the following topics: