##Visual Studio JavaScript Intellisense and Code Completion Support


**Overview**

Included in the .zip is `soapi-vsdoc.js`. This file contains JavaScript code documented following the [Visual Studio JavaScript Intellisense Documentation format][1].

This file, while of special interest to users of Visual Studio, contains complete documentation of the API, including all enumerated constant values and route parameter specifications.

For Visual Studio users: When using Soapi.JS in Visual Studio, the `-vsdoc.js` file simply needs to reside in the same directory as the `soapi.js` and `soapi.generated.js` files. Visual Studio will   

If you are using Visual Studio 2008, you may need to apply the [JavaScript Intellisense patch][2]. The patch specifies X86, but I can assure you that the same patch is applicable to both x86 and x64.


**Enums**

As described in the Enumerated Constants post, `soapi.js` define enums that can help you write stronger code against the Soapi.JS library.

In addition to the interesting 'enum' construct provided by `soapi`, the `soapi-vsdoc.js` file enhances the value of the enum types by adding Visual Studio Intellisense and Code Completion via the use of XML Documentation Comments.

![alt text][3]

**Factory Methods**

The factory's intellisense describe the route to be built:

![alt text][4]

The factory method's intellisense describe the route's 'id' parameters:

NOTE: The documentation is generated directly from the API, so it is assumed that the programmer will know that the 'semicolon-delimited string' description, in the context of Soapi.JS, describes, in the factory method call, a param array, and when setting parameters directly on the route, an array, which will be properly converted and encoded by `getResponse`.

![alt text][5]

The route's fields describe themselves:

NOTE: The documentation is generated directly from the API, so it is assumed that the programmer will know that the 'unix timestamp' description, in the context of Soapi.JS, describes a JavaScript `Date`, which will be properly converted and encoded by `getResponse`.


![alt text][6]

**Convenience Constructors**

When becoming acquainted with a new library, it is sometimes helpful to have code completion assistance and intellisense documentation for the objects returned from API calls.

By leveraging the `vsdoc` file and a special constructor function, we can build a 'casting' constructor that, if the object passed in is an instance of itself, simply return it, otherwise apply the object passed in to a new instance. This provides intellisense, code completion and method chaining via type inference. 

The properties of the response type are enumerated:

![alt text][7]

The fact that `users` is an array is demonstrated by the type inference provided by Visual Studio.

![alt text][8]

Casting an element of the `users` array to `Soapi.Domain.User` results in the same effect.

![alt text][9]


While this added functionality may seem trivial, in a scenario where one is dealing with a new/beta/constantly shifting API, this type of assistance can be a great productivity boost. Especially on objects that have many many members and nested objects.

It is Visual Studio's type inference functionality, driven by the `-vsdoc.js` file, that enables complete intellisense code-completion throughout the compact, or 'fluent', example that is given at the head of the question to this answer.


**Next**: [Date Handling in Soapi.js][10] - no more greasy unix timestamps.


  [1]: http://stackoverflow.com/questions/282129/intellisense-for-ajax-and-javascript-libraries-in-visual-studio
  [2]: http://code.msdn.microsoft.com/KB958502/Release/ProjectReleases.aspx?ReleaseId=1736
  [3]: http://soapi.info/images/soapi.js.enums1.png
  [4]: http://soapi.info/images/soapi-factory-intellisense1.png
  [5]: http://soapi.info/images/soapi-factory-intellisense2.png
  [6]: http://soapi.info/images/soapi-route-intellisense1.png
  [7]: http://soapi.info/images/soapi-intellisense-cc1.png
  [8]: http://soapi.info/images/soapi-intellisense-cc2.png
  [9]: http://soapi.info/images/soapi-intellisense-cc3.png
  [10]: http://stackapps.com/questions/494/soapi-js-dates/977#977