JSDoc Notes

From MemberWiki

Jump to: navigation, search

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"
}
Retrieved from "/member/wiki/JSDoc_Notes"
Personal tools