##Visual Studio JavaScript Intellisense and Code Completion Support
Overview
Included in the generated .zip is soapi.generated-vsdoc.js. This file contains JavaScript code documented following the Visual Studio JavaScript Intellisense Documentation format.
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. The summary information is generated directly from the StackOverflow API help pages.
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. 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 and soapi.generated.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.generated.js, the soapi.generated-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 http://soapi.info/images/soapi.js.enums1.png
Factory Methods
The factory's intellisense describe the route to be built:
alt text http://soapi.info/images/soapi-factory-intellisense1.png
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 http://soapi.info/images/soapi-factory-intellisense2.png
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 http://soapi.info/images/soapi-route-intellisense1.png
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 http://soapi.info/images/soapi-intellisense-cc1.png
The fact that users is an array is demonstrated by the type inference provided by Visual Studio.
alt text http://soapi.info/images/soapi-intellisense-cc2.png
Casting an element of the users array to Soapi.Domain.User results in the same effect.
alt text http://soapi.info/images/soapi-intellisense-cc3.png
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.