###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][1]
- [Java runtime][2] (TODO: see if [ikvm][3] can run jsdoc. I doubt it)
- [JsDoc ToolKit 2][4]

**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
 5. 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][5]


  [1]: http://aspnet.codeplex.com/releases/view/35893
  [2]: http://www.oracle.com/technology/software/index.html#java
  [3]: http://www.ikvm.net/
  [4]: http://code.google.com/p/jsdoc-toolkit/
  [5]: https://stackapps.com/questions/494/soapi-js-fluent-javascript-wrapper-for-the-stackoverflow-api-rc4/1116#1116