JSDoc Notes
From MemberWiki
Here are some notes on JSDoc that might be relevant to the IDE discussions.
Contents |
Assumption: separate JSON or XML file
These notes assume that:
- OpenAjax Alliance's IDE standards will pursue a strategy where there is a separate file (or files) that holds metadata about an Ajax library's APIs. IDEs would load this standard metadata file.
- If the developer and the toolkit are using inline annotations within the source code to document APIs, then there will be a software utility available that will convert the inline annotations into a separate file whose format will be defined by the IDE effort at OpenAjax Alliance
JSDoc's feature breadth
JSDoc supports a surprising (at least to me!) breadth of features.
- As expected, JSDoc recognizes /**...@foo...*/ markup, where @foo can be a variety of things. Here are some of the @foo keywords that are recognized
- @class
- @extends
- @constructor
- @param {<type>} <name> <desc>
- @throws
- @return
- @type
- @author
- @requires
- @see #anchor (hyperlink to #anchor)
- @link #anchor (hyperlink to #anchor)
- @private
- But JSDoc's smarts go beyond a simple preprocessor. JSDoc must include a JavaScript interpreter because it seems to be able to figure out inner classes, instance functions vs class functions, and maybe even closure situations. For example, it will recognize that Coordinate_GetX is a class function on the Coordinate class:
Coordinate.prototype.getX = Coordinate_GetX; /** * Gets the x portion of the Coordinate. * @type int */ function Coordinate_GetX() { return this.x; }
JSDoc's XML file
JSDoc includes a command line option ("--format xml") that will read in a JavaScript file annotated with JSDoc-formatted comments (e.g., @class, @param, @throws, @return) and produce as output an XML file that expresses JSDoc's data models.
JSDoc has a very reach feature set and therefore lots of options within its XML syntax. For quick illustrative purposes, here is a simple example of some annotated JavaScript:
/** * This is an unattached (static) function that adds two integers together. * @param {int} One The first number to add * @param {int http://jsdoc.sourceforge.net/} Two The second number to add * @author Gabriel Reid * @deprecated So you shouldn't use it anymore! */ function Add(One, Two){ return One + Two; }
the generated XML file will be:
<?xml version="1.0"?> <javascript> <classes> <class name="GLOBALS" > <constructor_args></constructor_args> <constructor_vars></constructor_vars> <constructor_detail><![CDATA[]]></constructor_detail> <instance-methods></instance-methods> <instance-fields></instance-fields> <class-methods> <method mapped_name="Add"> <description><![CDATA[This is an unattached (static) function that adds two integers together.]]></description> <argument_list>(One, Two)</argument_list> <vars> <var name="deprecated"> <value><![CDATA[So you shouldn't use it anymore!]]></value> </var> <var name="filename"> <value><![CDATA[test.js]]></value> </var> <var name="author"> <value><![CDATA[Gabriel Reid ]]></value> </var> <var name="param"> <value><![CDATA[{int} One The first number to add ]]></value> <value><![CDATA[{int http://jsdoc.sourceforge.net/} Two The second number to add ]]></value> </var> </vars> </method> </class-methods> <class-fields> </class-fields> <inner-classes> </inner-classes> </class> </classes> </javascript>
Suitability of JSDoc's XML syntax to our purpose
JSDoc's XML structures are not completely suitable as the final definition for what the IDE working group should use for its metadata format. There are probably multiple reasons, but here are a couple:
- We need a less roundabout way of expressing the structure
- We need to pull out the parameter name and type information from the description string
Therefore, instead of:
<var name="param"> <value>{int} One The first number to add&</value> </var>
or in JSON
{ var: { name:"param", value:"{int} One The first number to add" } }
The following would be more direct and therefore better to express this in a manner similar to
<param name="One" type="int"> <desc>The first number to add</desc> </param>
or, in JSON
param: { name:"One", type:"int", desc:"The first number to add" }