Return to Revisions

###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 Documentation Comments to support intellisense and code completion
2. JavaDoc style comments for use in generating HTML documentation 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 means of generating vs doc xml from POJO code. I have an abandoned and partially implemented project but have not taken the time to revive it for reasons that will become clear.
2. The JsDoc format is far more expressive than is the Xml Doc format and better than mix those concerns, I find it a much cleaner, albeit labor intensive, approach to use JsDoc Toolkit for generating hard 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 the doc file and the script
2. run JsDoc Toolkit to generate the doc site from the vsdoc (jsdoc) file into /build/docs
3. post process the output to clarify enums and create linked func parameters
4. run a search and delete of JsDoc comments to output a smaller vsdoc file.
5. write a vsdoc for Soapi.js and Soapi.min.js to the /build/scripts directory

Packaging The Distribution

1. copy all of the content and third party demo support scripts to build directory
2. copy the scripts and tests to the /build/scripts directory
3. use ajax minifier to compress the script and copy to the /build/scripts directory
4. gzip the minified script and copy to the /build/scripts directory
5. build 3 versioned dowload files in the /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