How to: Create JavaScript XML Documentation Comments

Article
04/28/2015

XML documentation comments are JavaScript comments that you add to a script to provide information about code elements such as functions, fields, and variables. In Visual Studio, these text descriptions are displayed with IntelliSense when you reference the script function.

This topic provides a basic tutorial on using XML documentation comments. For information about using other elements, such as <var> (JavaScript) and <value> (JavaScript), and for additional code examples, see XML Documentation Comments (JavaScript). For information about providing IntelliSense information for an asynchronous callback such as a Promise, see <returns> (JavaScript).

Note

XML documentation comments are available only from referenced files, assemblies, and services.

To create XML documentation comments for a JavaScript function

In the function, add <summary> (JavaScript), <param> (JavaScript), and <returns> (JavaScript) elements, and precede each element with three slash marks (///).

Note

Each element must be on a single line.

The following example shows a JavaScript function.

  function getArea(radius)
  {
      /// <summary>Determines the area of a circle that has the specified radius parameter.</summary>
      /// <param name="radius" type="Number">The radius of the circle.</param>
      /// <returns type="Number">The area.</returns>
      var areaVal;
      areaVal = Math.PI * radius * radius;
      return areaVal;
  }

To view the XML documentation comments, type the name and the opening parenthesis of a function that is marked with XML documentation comments, as in the following example:
```
var areaVal = getArea(
```
When you type the opening parenthesis of the function that contains the XML documentation comments, the Code Editor uses IntelliSense to display the information that is defined in XML documentation comments.

To create XML Documentation comments for a JavaScript field

In a constructor function or object definition, add a <field> (JavaScript) element preceded by three slash marks (///).

The following example shows the use of the <field> element in a constructor function. For additional examples, see <field> (JavaScript).
```
    function Engine() {
        /// <field name='HorsePower' type='Number'>The engine's horsepower.</field>
        this.HorsePower = 150;
    }
```
To view the XML documentation comments, create an object by using the function constructor that is marked with XML documentation comments, as in the following example.
```
    var eng = new Engine();
```
On the next line, type the name of the object and a period to show IntelliSense information for the field.
```
    eng.
```

To create XML documentation comments for an overloaded function

In the function, add a <signature> (JavaScript) element for each overload. In these elements, add other elements, such as <summary>, <param>, and <returns>, preceding each element with three slash marks (///).

The following example shows an overloaded JavaScript function. In this example, the overloads differ by parameter type.

    function calc(a) {
        /// <signature>
        /// <summary>Function summary 1.</summary>
        /// <param name="a" type="Number">A number.</param>
        /// <returns type="Number" />
        /// </signature>
        /// <signature>
        /// <summary>Function summary 2.</summary>
        /// <param name="a" type="String">A string.</param>
        /// <returns type="Number" />
        /// </signature>
        return a;
    }

To view the XML documentation comments, type the name and the opening parenthesis of the function that is marked with XML documentation comments, as in the following example:
```
    calc(
```

To create localized IntelliSense

Create an XML file that has documentation comments in the OpenAjax MessageBundle format.

Important

MessageBundle is the recommended format. This format is not supported in Microsoft Ajax or in .winmd files. For information about using the alternative VSDoc format, see <loc> (JavaScript).

The following example shows content in a sidecar file that contains the localized IntelliSense information. This is an XML file that's located in a culture-specific folder, like JA. The folder must be in the same location as the .js file that contains the <loc> element. The file name of the XML file must match the filename parameter specified in the <loc> element.
```
<messagebundle>
  <msg name="1">A class that represents a rectangle</msg>
  <msg name="2">The length of the rectangle</msg>
  <msg name="3">The height of the rectangle</msg>
</messagebundle>
```
In your .js file, add the following code. The <loc> element must be declared before any script, and follows the same usage rules as the <reference> element. For more information, see JavaScript IntelliSense and <loc> (JavaScript).
```
/// <loc filename="messageFilename.xml" format="messagebundle"/>
```
In your .js file, add the XML documentation elements and default descriptions. Set the locid attribute values to match the corresponding name attribute values from the sidecar file. The default descriptions will be replaced by localized IntelliSense information, if it's available.
```
function add(a,b) 
{
    /// <summary locid='1'>description</summary>
    /// <param name='a' locid='2'>parameter a description</param>
    /// <param name='b' locid='3'>parameter b description</param>
}
```
To view the XML documentation comments, type the name and the opening parenthesis of the function, as in the following example:
```
add(
```

Share via

How to: Create JavaScript XML Documentation Comments

To create XML documentation comments for a JavaScript function

To create XML Documentation comments for a JavaScript field

To create XML documentation comments for an overloaded function

To create localized IntelliSense

See Also

Concepts

Other Resources

Additional resources