##Visual Studio JavaScript Intellisense and Code Completion Support
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.
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. 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.
Factory Methods
The factory's intellisense describe the route to be built:
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.
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.
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:
The fact that users is an array is demonstrated by the type inference provided by Visual Studio.
Casting an element of the users array to Soapi.Domain.User results in the same effect.
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 - no more greasy unix timestamps.
