Problem

In my programming environment I have strong support for code-completion through IntelliSense. I would like the same feature when I'm working with the jQuery library.

Solution

Visual Studio 2008 SP1 and Visual Studio 2010 use formatted comments in JavaScript source files in a very similar fashion to c# and VB.NET. By leveraging readily available commented versions of the jQuery library you'll get the full-featured power of IntelliSense.

Don't have a documentation file? Even without the specialized commenting IntelliSense works with library references to give you a rich set of features such as code-completion and method signature information.

Additionally, you can learn to apply comments to expose summary and parameter information for the code in your own libraries.

The Goal

What we're looking for is pretty straightforward. Basically, we want to see object members, code-completion and parameter information. It should look something like this:

This is achieved by including a special version of jQuery in our project. You will need to download a copy of this documention from the jQuery web site, listed as "Visual Studio" in the Documentation section of the downloads. The downloaded file name will include "vsdoc", as in "Visual Studio Documentation", in it's name.



Grab a copy of the file and add it to your project, saving it in the same directory as the jQuery library.

Enabling IntelliSense in a Web Form or View Page

Remeber, you can get most of IntelliSense's features (code completion, limited parameter information) even when the file you reference does not have a commented version available. But, once you've put a properly-formatted VSDoc file in the same directory as the jQuery library you've done all you need to do to get all aspects of the tool. The rest is up to Visual Studio.

Visual Studio opportunistically searches for documentation files (and debug versions of your libraries) in the same directory as any script you've referenced. Following a naming convention with the name of a library as a root, for example jquery-1.4.1.js, the IDE will search for:

• jquery-1.4.1-vsdoc.js, then if the IDE can't find it will search for...
• jquery-1.4.1.debug.js, then if the IDE can't find it will search for...
• jquery-1.4.1.js

These files are sought out for any script reference you make, be it as standard HTML script tags, in ASP.NET Script Manager and Script Manager Proxy tags, as well as in XML comment references (which we'll see in a moment).

This makes it easy for any developers who already have debug versions of their scripts with the "dot debug" convention. By keeping the VSDoc or DEBUG files next to your runtime version you give the IDE everything it needs to serve up some IntelliSense coolness.

Enabling IntelliSense in a Script

You can take advantage of the same great feature in script files, too. The idea is the same, but the markup is a little simpler; it is achieved through XML comment references:
That one line at the top of a stand-alone JavaScript file is all you need, provided the VSDoc file is in the same directory.

Visual Studio 2010, IntelliSense and the CDN

We'll shift gears here quickly and talk about Content Delivery Networks, or CDNs. CDNs are made up of multiple servers, positioned at critical sites world wide. These servers all host the same set of files, allowing the closest server to the user respond to the request for a given file. CDNs reduce the amount of traffic on the internet by serving content locally with the added benefit of increasing the performance of downloads for users.

Why is this relevant to IntelliSense and Visual Studio 2010? With the latest version of the IDE you are now able reference files that are not located locally, i.e., that are out on the network somewhere, including on a CDN.

Have a look at how you can do this with the jQuery library:

Let's consider some of the immediate benefits gained by this feature of VS 2010:

• you get the same opportunistic VSDoc and DEBUG file searching from the cloud and don't have to download the documentation files
• you don't have to download or deploy the library itself
• you will likely improve the download speed of your web page for users
• some CDNs will automatically serve the latest copy of a script if you omit the revision number, meaning your pages will benefit from performance or security upgrades as they become available

Again, Visual Studio 2008 SP1 will not grab the files off the network; however it is able to grab VSDoc and DEBUG files from the local file system.

Getting IntelliSense for Your Script Files

Excellent, so we're humming along with jQuery and - in Visual Studio 2010 - we're able to take advantage of IntelliSense from files even if they live in the cloud, but eventually we're going to have to write our own code too, right?

So, how do we get IntelliSense for our own libraries?

Let's examine the following script:

Let's assume the code above is stored in a file called shapes.js and that we have it referenced in the source file we're working on, as we did with the jQuery library. With no extra effort we get code completion and some hinting about the method's parameters.



We see member variables, methods defined through closure as well as through the prototype, and this is all free. To take it to the next level we're going to have to resort to a trick we've been using for years in Visual Studio with a syntax meant for documentation.

Consider the revised script:

With a set of triple slashes and some XML style comments, we can now unleash IntelliSense on our code with full force:



For a complete breakdown of how to fully comment your library see this post by Bertrand Le Roy.

Wrapping Up

IntelliSense is a feature that just keeps getting better in every release of Visual Studio. Over the years it has evolved from it's humble beginnings adding features, additional languages, pre-compilation support, richer interaction from within the IDE, and now even support for files in the cloud. It's likely something that you use already, so you'll be glad to see such strong support for jQuery with this excellent tool.