Answer by Sky Sanders for OBSOLETE - Soapi.JS : fluent JavaScript client library for the Stack Exchange API

Packaging Soapi.js

The process of packaging Soapi.js for distribution may be of interest to users of Soapi.js as well as others interested in using Visual Studio to automate the build and packaging of JavaScript resources, including documentation.

Requirements:

• Visual Studio 2008
• Ajax Minifier 1.1
• Java runtime (TODO: see if ikvm can run jsdoc. I doubt it)
• JsDoc ToolKit 2

Generating the documentation

The documentation of Soapi.js is built from Soapi-vsdoc.js comprised of two parts:

1. Visual Studio Xml DocumentationComments to support intellisense andcode completion
2. JavaDoc stylecomments for use in generating HTMLdocumentation with JsDoc Toolkit

example:

/*** Global success handler. Replace (override) this method. This event is raised before the instance success function.* @function* @static* @param {Object} data The response data* @param {Object} [context] An arbitrary user defined value/object*/Soapi.onSuccess = function(data, context){    /// <summary>Global success handler. Replace (override) this method. This event is raised before the instance success function.</summary>    /// <param name="data" type="Object">The response object</param>    /// <param name="context" type="Object">An arbitrary user defined value/object</param>};

There are a few reasons for the duplicated effort.

1. There is currently no public meansof generating vs doc xml from POJOcode. I have an abandoned andpartially implemented project buthave not taken the time to reviveit for reasons that will becomeclear.
2. The JsDoc format is far moreexpressive than is the Xml Docformat and better than mix thoseconcerns, I find it a much cleaner,albeit labor intensive, approach touse JsDoc Toolkit for generatinghard copy docs.

There are a few features that JsDoc Toolkit does not support, so there are some post processing that needs to be done.

1. update the build number in both thedoc file and the script
2. run JsDoc Toolkit to generate thedoc site from the vsdoc (jsdoc) fileinto /build/docs
3. post process the output to clarifyenums and create linked funcparameters
4. run a search and delete of JsDoccomments to output a smaller vsdocfile.
5. write a vsdoc for Soapi.js andSoapi.min.js to the /build/scriptsdirectory

Packaging The Distribution

1. copy all of the content and thirdparty demo support scripts to builddirectory
2. copy the scripts and tests to the/build/scripts directory
3. use ajax minifier to compress thescript and copy to the/build/scripts directory
4. gzip the minified script and copy tothe /build/scripts directory
5. build 3 versioned dowload files inthe /download
   1. zipped docs only
   2. zipped scripts only
   3. all content including docs, scripts, tests, demos and examples
6. manually review tests and deploy to public sites

All of this could be built into a custom MSBuild task, but for now it is being performed by the included console application, Soapi.JS.Deploy, that is run on successful builds.

Next:Request Caching