Visual Studio 2008 adds support for the JavaScript development environment through IntelliSense help for JavaScript class libraries. IntelliSense is enabled by adding script references at the head of the JavaScript file. Each file should list core libraries that it references in the form of script references. Script references can be named resources for compiled assemblies, such as the Microsoft AJAX Library itself, or path-based references. To add a reference to the AJAX library, include the following line at the top of your JavaScript file:

/// <reference name="MicrosoftAjax.js"/>

For assemblies other than the AJAX library, you need to include the assembly name in the script reference. For example, to include a reference to MyLibrary.js compiled into the assembly MyAssembly.dll, the following script reference would be added:

/// <reference assembly="MyAssembly" name="MyLibrary.js"/>

To add a reference to a custom library, include a reference with a path as follows:

/// <reference path="Controls/ApplicationRuntime.js"/>

Within the class library, IntelliSense will be enabled within the file for items that are declared above the line of code you’re working on and also in any files referenced through script reference comments. Within an ASPX page, IntelliSense is enabled for all files that have been references through the ScriptManager control.

When the IDE parses for IntelliSense, it also does a round of error checking and will complain in the Error window if any errors are found. To force the IDE to update its JavaScript IntelliSense, press the keyboard combination CTRL-ALT-J.

The XML comments used in JavaScript are similar to those used in C#: three slashes precede a comment, and the comment uses standard comment elements defined by the Visual Studio IntelliSense engine. The standard elements are summary for class definitions, value for field definitions, param for method parameters, and returns for return types. JavaScript XML comments are always declared inside the method or class definition.

For each class definition, provide a summary of the class in its constructor method. The following example demonstrates the comments for a class constructor (in the function definition):

ExampleClassDefinition = function() {
    /// <summary>
    /// An example class, to demonstrate XML comments.
    /// </summary>
}

Properties are defined in the Microsoft AJAX Library by convention with get and set methods defined in the class prototype. Within the property, define the comment in the get method, as the following code demonstrates:

get_xml: function() {
    /// <value>Gets or sets the XML data</value>
    return this._xml;
},
set_xml: function(value) {
    this._xml = value;
}

The value element has the optional attributes type, integer, domElement, and mayBeNull. These attributes can be used to further define the value, although I generally prefer lightweight documentation with only the description defined. The following value element lists its optional attributes.

<value
    type="ValueType" integer="true|false" domElement="true|false"
    mayBeNull="true|false" elementType="ArrayElementType">Description</value>

Additionally, whenever arrays are passed, the following attributes can be added to value, param, or returns elements to specify the contents of the array elements: elementType, elementInteger, elementDomElement, and elementMayBeNull.

Events are defined by add and remove methods, which are explained in depth in Chapter 7 in the discussion of Sys.Component. For reference, you define the handler XML comments in the add method as the following code demonstrates:

add_render: function(handler) {
    /// <value>Bind and unbind to the render event.</value>
    this.get_events().addHandler('render', handler);
},
remove_render: function(handler) {
    this.get_events().removeHandler('render', handler);
}

For methods with parameters (including the constructor or function), the param element can be used to define the expected type of parameter. For example, the following code demonstrates the param definition for a method that expects a Sys.UI.DomEvent argument:

function testHandler(event){
    /// <param name="event" mayBeNull="false" optional="false"
    /// type="Sys.UI.DomEvent">The event from the user click</param>
}

The following param element lists its optional attributes:

<param name="parameterName" mayBeNull="true|false" optional="true|false"
    type="ParameterType" parameterArray="true|false" integer="true|false"
    domElement="true|false">Description</param>

IntelliSense within the method body is inferred through instantiation of the object. It doesn’t matter what XML comments are provided for the method parameters. You won’t get IntelliSense inside the method without creating a type inference through instantiation. When you know what type to expect in a method, set the parameter to an instance of the expected type in validation code that runs only if the argument is not passed. For example, the following pageLoad method adds the testHandler event handler to the click event of a DOM object. To enable IntelliSense within the body of the method, create an object and throw an error when the argument is null. Because the argument will never be null (unless there really is an error), the code will not be called under normal use, but you can implement the method body more quickly during development than by referring to external code documentation. The following example demonstrates how to create a type inference through object creation:

function pageLoad() {
    var target = $get('TestNode'),
    Sys.UI.DomEvent.addHandler(target, 'click', testHandler);
}

function testHandler(event){
    ///<param name="event" mayBeNull="false" optional="false"
    /// type="Sys.UI.DomEvent">The event from the user click</param>

    // Type inference enables intellisense:
    if (event == null){ event = new Sys.UI.DomEvent(); throw 'Invalid Operation';}
    // intellisense is enabled for Event here, now known as a Sys.UI.DomEvent
}

Finally, for objects that return an item, the returns element should be used to specify the type of object that is returned. The following code sample demonstrates the XML comments for a method that returns a random DOM element. The domElement=true attribute is set, specifying that the method returns a DOM element.

function getRandomDomElement() {
    /// <summary>Gets a random DOM element</summary>
    /// <returns type="object" domElement="true" mayBeNull="true">
    ///   Returns a random DOM element.
    /// </returns>
    throw Error.notImplemented();
}

Tip

Although XML comments add tremendous value in the form of documentation, I believe that the best code is the simplest code and that documentation should be lightweight. Because JavaScript is a loosely typed language, I prefer to keep strong references out of the documentation as well. I typically avoid the optional parameters for the elements and keep the code and the documentation as simple as possible.