It should be no surprise that JScript Documentation Comments power much of what you see in JScript IntelliSense in VS2008.  Perhaps the most useful of these comments is the “reference” comment.  The “reference” comment allows you to “see” functions and objects outside of your current file in the completion list.  I’ve gotten quite a few questions about this feature so, I wanted to provide a reference for when and how to use it.  There are four usage patterns:

Referencing Another JS File

/// <reference path=”path-to/another-script.js” />

If the “path” attribute points to another JS file, any objects or functions defined inside that file-or in a file referenced by that file-will show up in IntelliSense.  Yes, this implies a transitive closure.  The intent was to reduce the number of references you would need on any given file.  Thus, don’t be surprised if more scripts show up to the party than you invited!

Referencing a Web Service

/// <reference path=”path-to/wcf-service.svc” />
/// <reference path=”path-to/asmx-service.asmx” />

If the “path” attribute points to a web service (either WCF or ASP.NET), any objects or functions defined in the generated proxy for that service will show up in IntelliSense.  Web service proxies in JScript are an ASP.NET AJAX feature.  Therefore it is critical that you reference “MicrosoftAjax.js” before you reference any web services.

Referencing a Web Page

/// <reference path=”path-to/default.aspx” />

If the “path” attribute points to a page (an ASPX, HTML, or Master), IntelliSense will behave as if you were on the page.  This mode is really just syntactic sugar and behaves equivalently to manually copying each script reference from the page over to your script file.  The only difference is that you will not see any inline script blocks reflected in IntelliSense.  However, you will be able to reference any elements with an ID on the page.  Any scripts or elements included via a Master page will also be reflected.  This mode useful for scripts that are meant to be paired exclusively with a markup page, i.e. in a “code-beside” fashion.

Referencing an Embedded Resource

/// <reference name=”resource-name” />
/// <reference name=”resource-name” assembly=”assembly-name” />

We recognized that scripts will frequently be embedded inside an assembly.  To reference such a script, set the “name” attribute to the resource name, and set the “assembly” attribute to the assembly name.  The “assembly” attribute is optional.  If left out, System.Web.Extensions will be assumed as the assembly.  This is why referencing “MicrosoftAjax.js” does not require an “assembly” attribute.

Other Hints

Here are a few other subtle tips:

• Remember, reference statements must precede all other content in the file-even normal comments.
• Make sure any dependencies are taken into account in the order of declarations. Most of the time, you will want “MicrosoftAjax.js” to be on the top.
• You can use app-relative paths (~/folder/file) to make your references more robust.
• Specifying “.debug.js” extension is optional. The editor will look for the “.debug.js” version of your script even if you only specified “.js”. This intentionally behaves similarly to the ScriptReferences of the ScriptManager.
• To combat the tedium of typing large amounts of these reference statements, try the dragging and dropping files from the solution explorer onto the editor to automatically generate these statements. It even works for DLLs.

Hope this helps!

Jeff King
Program Manager
Visual Studio Web Tools