[OpenAjaxIDE] Progress on JSDoc to OpenAjax Metadata converter

Jon Ferraiolo jferrai at us.ibm.com
Mon Aug 18 17:28:48 PDT 2008



(sorry if this is a duplicate - my first attempt didn't show up in the
archives)

I have completed  version 0.1 of an add-on to JSDoc Toolkit (
http://code.google.com/p/jsdoc-toolkit/) which allows creation of an
OpenAjax Metadata file (i.e., *.oam.xml) out of any JavaScript file. I have
had success running this software against some JavaScript files in jMaki
and YUI (albeit with some warnings and errors from JSDoc Toolkit which I
haven't investigated yet).

It turns out that JSDoc Tookit is a pretty neat bit of software. One of its
nice features is that it allows custom generators to be added to its
back-end. I have developed an "openajax" back-end that produces API
metadata files. Another neat thing about JSDoc Toolkit is that it is
written in JavaScript. Therefore, you have this nice self-referential cycle
in that JSDoc Toolkit's own implementation can be processed by JSDoc
Toolkit. JSDoc Toolkit includes the Rhino parser, which allows it to
process all (?) of the various weird techniques one can use to define
various constructs (e.g., functions, constructors, classes) in JavaScript.

Because JSDoc Toolkit is written in JavaScript, my "openajax" add-on is
also written in JavaScript. I annotated my JavaScript with JSDoc inline
comments and then ran my JavaScript file through JSDoc Toolkit, producing
an OpenAjax Metadata file that describes the JavaScript APIs. To
illustrate, here is a snippet of JavaScript from the openajax add-on:

Original JavaScript:

      /**
      * Processes a method found in the JSDoc data structure.
      * Produces an OpenAjax 'method' element.
      * @param {object} method JSDoc object that holds info on this method
      * @param {number} indent Current indent level for pretty printing
      */
      this.method_element = function(method, indent) {

Corresponding OpenAjax Metadata that was generated:

            <method name="method_element">
                  <description>
                        Processes a method found in the JSDoc data
structure.
                        Produces an OpenAjax 'method' element.
                  </description>
                  <parameter name="method" datatype="Object"
usage="required">
                        <description>
                              JSDoc object that holds info on this method
                        </description>
                  </parameter>
                  <parameter name="indent" datatype="Number"
usage="required">
                        <description>
                              Current indent level for pretty printing
                        </description>
                  </parameter>
            </method>


So far, I have partial implementations for the following:

elements: api, author, class, constructor, description, field, globals,
method, namespace, parameter, returns
attributes: datatype, default, name, required, usage, version,

I am planning to check in my code into the OpenAjax SourceForge project
this week. I hope to continue development of this OpenAjax add-on such that
we can produce OpenAjax Metadata automatically out of many popular Ajax
toolkits and learn about what problems we encounter at the detailed level.
My next big research effort in this area is to see if JSDoc Toolkit has
hooks that allow it to process other forms in inline JavaScript
documentation, such as what Dojo uses or what Microsoft uses in ASP.NET
AJAX.

Jon

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://openajax.org/pipermail/ide/attachments/20080818/ee74a403/attachment-0001.html 


More information about the IDE mailing list