csnover / js-doc-parse Goto Github PK

define([], function(){
    // summary:
    //      This comment gets lost
    return 123;
});

generates:

<object location="dojox/mobile/_compat" type="number">
<properties/>
<methods/>
</object>

IIUC the idea was that you could have a summary either on the module, or on the return value (and there shouldn't be duplication). But it seems only the summary on the return value works.

cc @cjolif

It looks like a commit to fix the comments has broken the parser. This changeset 29111 seems to be causing the following when running the parser:

Processing module dojo/_base/kernel (6.03M used / 17.41M RSS)
ERR: dojo/_base/kernel.js:1:52 TypeError: Cannot read property '1' of null
    at processComment (/Users/kitsonk/github/js-doc-parse/lib/processor/dojodoc.js:244:31)
    at Object.generateMetadata (/Users/kitsonk/github/js-doc-parse/lib/processor/dojodoc.js:383:17)
    at /Users/kitsonk/github/js-doc-parse/lib/esprimaParser.js:63:14
    at Array.forEach (native)
    at attachMetadata (/Users/kitsonk/github/js-doc-parse/lib/esprimaParser.js:46:18)
    at createFunctionValue (/Users/kitsonk/github/js-doc-parse/lib/esprimaParser.js:81:3)
    at Object.FunctionExpression (/Users/kitsonk/github/js-doc-parse/lib/esprimaParser.js:502:16)
    at read (/Users/kitsonk/github/js-doc-parse/lib/esprimaParser.js:239:27)
    at Object.CallExpression (/Users/kitsonk/github/js-doc-parse/lib/esprimaParser.js:350:43)
    at read (/Users/kitsonk/github/js-doc-parse/lib/esprimaParser.js:239:27)

Dijit used to parse but now gets an exception in _PaletteMixin.js on a field called "summary":

// summary: String
//      Localized summary for the palette table
summary: '',

If I want to distribute js-doc-parse with a dojo version I don't want dojo to be a child directory of js-doc-parse. I want for example js-doc-pase in the dojo/utils directory. There should be a way to specify where to load dojo when running the tool.

When running parse.sh on the dojo/ directory (dojo core code), it gets confused about which methods belong to which objects. For example, AdapterRegistry is listed as having the animation functions:

<object location="dojo/AdapterRegistry" type="function">
<properties>...</properties>
<methods>
<method name="_anim" scope="prototype" type="function" from="dojo/NodeList-fx">...</method>
<method name="wipeIn" scope="prototype" type="function" from="dojo/NodeList-fx">
<parameters>

Create a processor for handling jsdoc code comments.

Although for unknown reasons the summary is supposed to be plain text, my understanding is that attribute definitions are markdown. For example from _WidgetBase.js:

// containerNode: [readonly] DomNode
//      Designates where children of the source DOM node will be placed.
//      "Children" in this case refers to both DOM nodes and widgets.
//      For example, for myWidget:
//
//      |   <div data-dojo-type=myWidget>
//      |       <b> here's a plain DOM node
//      |       <span data-dojo-type=subWidget>and a widget</span>
//      |       <i> and another plain DOM node </i>
//      |   </div>
//
//      containerNode would point to:
//
//      |       <b> here's a plain DOM node
//      |       <span data-dojo-type=subWidget>and a widget</span>
//      |       <i> and another plain DOM node </i>
//
//      In templated widgets, "containerNode" is set via a
//      data-dojo-attach-point assignment.
//
//      containerNode must be defined for any widget that accepts innerHTML
//      (like ContentPane or BorderContainer or even Button), and conversely
//      is null for widgets that don't, like TextBox.
containerNode: null,

The generated XML doesn't have <pre> or <code> for those example blocks, nor are there any <p> tags to separate the paragraphs (including the last two paragraphs):

<property name="containerNode" scope="prototype" type="null" from="dijit/_WidgetBase">
<summary>
Designates where children of the source DOM node will be placed. "Children" in this case refers to both DOM nodes 
and widgets. For example, for myWidget: <div data-dojo-type=myWidget> <b> here's a plain DOM node 
<span data-dojo-type=subWidget>and a widget</span> <i> and another plain DOM node </i> </div> containerNode
 would point to: <b> here's a plain DOM node <span data-dojo-type=subWidget>and a widget</span> <i> 
and another plain DOM node </i> In templated widgets, "containerNode" is set via a data-dojo-attach-point
 assignment. containerNode must be defined for any widget that accepts innerHTML (like ContentPane
 or BorderContainer or even Button), and conversely is null for widgets that don't, like TextBox.
</summary>
</property>

Sorry for the long issue titles...

If a field (such as the postCreate method defined in dijit/_WidgetBase) has not been overridden, don't include the full definition of that field in the output; instead, let that definition be available by reference using a self-closing node. In other words, if you were looking at the XML data for dijit/Calendar and postCreate has not been overridden, let the method definition in dijit/Calendar look like so:

<method name="postCreate" from="dijit/_WidgetBase" />

This will also help cut down on the size of the resulting output.

    // _radius: Number
    // tags:
    //      private
    _radius: 100,

gives

<properties>
  <property name="_radius" scope="prototype" type="Number"
  from="dojox/dgauges/components/default/CircularLinearGauge" />
  ...
</properties>

See for example dijit/form/MultiSelect :: getSelected():

getSelected: function(){
    // summary:
    //      Access the NodeList of the selected options directly
    return query("option",this.containerNode).filter(function(n){
        return n.selected; // Boolean
    }); // dojo/NodeList
},

The XML output is listing the type as undefined:

<method name="getSelected" scope="prototype" type="function" from="dijit/form/MultiSelect">
<parameters/>
<return-types>
<return-type type="undefined"/>
</return-types>
<summary>
<p>Access the NodeList of the selected options directly</p>
</summary>
</method>

Needed for installation via npm cpm etc.

We have a number of occurrences of classes (for instance in dijit and dojox) where a module adds properties to some class with code such as:

lang.extend(dijit._WidgetBase, {
   alt: "",
   ...            
});

Now, the effect on the API doc is that the doc of completely unrelated classes wrongly shows that they would have these properties, if and only if these unrelated classes happen to be parsed by js-doc-parse after the class which extends its baseclass.

An example of this situation: the API doc of dojox/treemap/TreeMap shows the properties added to dijit/_WidgetBase by the completely unrelated dojox/mobile/Accordion, dojox/mobile/ListItem, dojox/mobile/i18n, dijit/layout/StackContainer, dijit/layout/BorderContainer etc.
These properties do NOT appear on the doc of other subclasses of _WidgetBase that are lexicographically located before the classes that add these properties.

There are two issues here:
1/ It does not seem expected that the API doc contains these added properties depending on the parsing order (which is the alphabetical one).
2/ Is there a recommended/standard way to tell the parser to ignore this call of dojo/_base/lang.extend for the purpose of the API doc? For now the only way we found is to use a single line construct such as:

/* ===== // ===== */ lang.extend(WidgetBase, { alt: "", ... });

(since we can't embed slash-star comments inside slash-star comments).
But this solution is fragile and may give huge lines of code... So there should be a better way.

From _WidgetBase, postscript() has a private tag:

postscript: function(/*Object?*/params, /*DomNode|String*/srcNodeRef){
    // summary:
    //      Kicks off widget instantiation.  See create() for details.
    // tags:
    //      private
    this.create(params, srcNodeRef);
},

but it's not picked up:

<method name="postscript" scope="prototype" type="function" from="dijit/_WidgetBase">
<parameters>
<parameter name="params" type="Object" usage="optional"/>
<parameter name="srcNodeRef" type="DomNode|String" usage="required"/>
</parameters>
<return-types/>
<summary>
Kicks off widget instantiation. See create() for details.
</summary>
</method>

Likewise for other tags, but I filed #20 for that issue since you already closed this ticket.

cc @pruzand

It's near-impossible to setup a summary/description for modules using "exports". For example see dojo/dom-attr.js.

I tried to hack it with by adding this to the end of the file, but it didn't work:

/*=====
var ret = {
    // summary:
    //      This module defines the core dojo DOM attributes API.
};
lang.mixin(ret, exports);
return ret;
=====*/

See also http://bugs.dojotoolkit.org/ticket/13769#comment:40, it's not trivial to remove the use of exports.

It seems that any variables that have a "standard key" for their name break the parser.

See dijit/_PaletteMixin for an example. Here we have a variable named "summary" that breaks the parser with : TypeError: Cannot read property 'type' of undefined

// summary: String
//      Localized summary for the palette table
summary: '',

I also tested it with 'example' and that also failed (although this file is the only live example I have come across) . Changing the name to anything else works fine.

This is where I got stuck trying to fix up errors in the dojo/ and dijit/ files that trip up the doc parser:

mac:docparse bill$ ./parse.sh dojo/main.js
...
debug: Resolving dependency ./_base/kernel
debug: Getting module dojo./_base/kernel
debug: Module not in cache, retrieving by file
ERR: dojo/main.js:18:2 Error: ENOENT, no such file or directory 'dojo./_base/kernel.js'

(Notice how it's dojo. rather than just dojo)

It seems that for examples, the js-doc-parse is wrapping examples in both <pre> and <code>. This is causing spacing issues in the API viewer, which can be somewhat offset by CSS styling, but it would be very handy that if something is already in a <pre> block, that it doesn't also get <code> wrapped.

Would be nice to be able to include code examples in the API doc of properties, just as for classes or methods.

For maximum consistency with the way we include examples for classes and methods, the doc of properties may support an "example" section, say:

// myProp: Object
//      This is a property.
// example:
// |    an example of usage
myProp: null,

Or at least to be able to include code blocks:

// myProp: Object
//      This is a property. Here is an example:
// |    an example of usage
myProp: null,

The "Dojo Inline Documentation" (http://livedocs.dojotoolkit.org/util/doctools/markup#using-markdown ) also mentions the use of backticks for inline pieces of code, however this does not seem to work in the API doc of properties (tried the sourrounding with one backticks and with three backticks): the XML includes the backticks as-is.

This is different from #24.

I'm seeing "undefined" listed unnecessarily as a return type from dijit/a11y.js::hasDefaultTabStop(). A simpler test case is:

dijit.hasDefaultTabStop = function(/*Element*/ elem){
    return true;
};

It gets flagged as having two return types.

There's something weird going on because I can make the hasDefaultTabStop() definition work by changing the definition of isTabNavigable() (which calls hasDefaultTabStop()).

According to http://stackoverflow.com/editing-help/#advanced-lists, markdown supports nested lists by indenting four spaces.

However, it doesn't work in our doc, for example dojox/string/BidiEngine.js:

//      As of February 2011, Bidi engine has following limitations:
//
//          1. No support for following numeric shaping options: 
//              - H - Hindi,
//              - C - Contextual,
//              - N - Nominal.
//          2. No support for following shaping options:
//              - I - Initial shaping,
//              - M - Middle shaping,
//              - F - Final shaping,
//              - B - Isolated shaping.
//          3. No support for source-to-target or/and target-to-source maps.
//          4. No support for LRE/RLE/LRO/RLO/PDF (they are handled like neutrals).
//          5. No support for Windows compatibility.
//          6. No support for  insert/remove marks.
//          7. No support for code pages (currently only UTF-8 is supported. Ideally we should convert from any code page to UTF-8).

Our doc is actually using tabs rather than spaces, so as an experiment, I tried switching to spaces, but that didn't help.

cc @AdrianVasiliu

The old version of dojo/behavior.js ([28901]) had code like:

return new function(){
     this.foo = function(a,b,c){ ... };
     ...
};

The parser wasn't picking up the function definitions.

I worked around the problem though.

When I run:

$ ./parse.sh ../trunk/dojo

the parser gets confused about paths, leading to an error:

ERR: ../trunk/dojo/_base/array.js:1:41 Error: ENOENT, no such file or directory '../trunk/dojo/trunk/dojo/_base/kernel.js'

Notice how "trunk/dojo" is repeated in the path.

See newest dojo/Deferred.js. The definitions for the methods are coming through, but the definition for "promise" isn't.

IIUC the plan was that for modules that return a hash containing classes, that all of each class' data will be be shoved into the description of that attribute.

So for example dojox/gfx/shape.js has:

var shape = g.shape = {
    // summary:
    //      This module contains the core graphics Shape API.
    //      Different graphics renderer implementation modules (svg, canvas, vml, silverlight, etc.) extend this
    //      basic api to provide renderer-specific implementations for each shape.
};
...
shape.Rect = declare(shape.Shape, {
    // summary:
    //      a generic rectangle
    constructor: function(rawNode){
        // rawNode: Node
        //      The underlying graphics system object (typically a DOM Node)
        this.shape = g.getDefault("Rect");
        this.rawNode = rawNode;
    },
    getBoundingBox: function(){
        // summary:
        //      returns the bounding box (its shape in this case)
        return this.shape;  // dojox.gfx.Rectangle
    }
});

But there's no real info about Rect in the output file:

<method name="Rect" scope="normal" type="constructor" from="dojox/gfx/shape">
<parameters/>
<return-types/>
</method>

cc @cjolif

Hi,

It seems the current parser does not take into account the "documentation hint" that may be specified for the return value.

For ex:

    bar : function(){
        return "asdf";
    },
    getBarFoo:function(){
        // summary:
        //      adf askdfj asdf asdf asdf 
        var a = this.bar();
        return a;   // String
    },

which gives:

  <method name="bar" scope="prototype" type="function" from="dojox/geo/openlayers/Map">
    <parameters/>
    <return-types>
      <return-type type="string"/>
    </return-types>
  </method>
  <method name="getBarFoo" scope="prototype" type="function" from="dojox/geo/openlayers/Map">
    <parameters/>
    <return-types>
      <return-type type="undefined"/>
    </return-types>
    <summary>adf askdfj asdf asdf asdf</summary>
  </method>

Also, if the keywod "returns" is used, it adds an extra any element:
bar : function(){
// summary:
// adf asdf alsfqwe
// returns:
// something interesting.
return "asdf";
},

gives:

  <method name="bar" scope="prototype" type="function" from="dojox/geo/openlayers/Map">
    <parameters/>
    <return-types>
      <return-type type="any"/>
      <return-type type="string"/>
    </return-types>
    <return-description>something interesting.</return-description>
    <summary>adf asdf alsfqwe</summary>
  </method>

cc @cjolif

In dojox/charting/action2d/Base.js there is:

constructor: function(chart, plot){
    // summary:
    //      Create a new base action.  This can either be a plot or a chart action.
    // chart: dojox.charting.Chart
    //      The chart this action applies to.
    // plot: String?|dojox.charting.plot2d.Base?
    //      Optional target plot for this action.  Default is "default".
    this.chart = chart;
    this.plot = plot ? (lang.isString(plot) ? this.chart.getPlot(plot) : plot) : this.chart.getPlot("default");
},

Since the parser can't resolve dojox.charting.chart or dojox.charting.plot2d.Base it's supposed to pass them through to the XML file as-is, right?

But rather,they are listed as type="undefined":

<method name="constructor" scope="prototype" type="function" from="dojox/charting/action2d/Base">
<parameters>
<parameter name="chart" type="undefined" usage="required">
<summary>The chart this action applies to.</summary>
</parameter>
<parameter name="plot" type="undefined" usage="required">
<summary>
Optional target plot for this action. Default is "default".
</summary>
</parameter>
</parameters>

cc @cjolif

The current output of the parser seems to duplicate full object definitions when outputting an XML file; in other words, if more than one module includes the same source object, the entire object's definition seems to be included in the output.

It would be more efficient if the processor looked to see if a module's definition has already been included in the output, and then simply use a self-closing tag to reference it. For example, if dojo/_base/kernel has already had it's full definition included in an output, any other reference to it would look something like:

<object location="dojo/_base/kernel" />

This would reduce the size of the output tremendously.

for example dojox/trunk/charting/action2d/_IndicatorElement the class does have a private tag but that is not reflected in the XML (I did not pull the latest updates thought).

See also #25.

dojo/parser.js has this code:

// scripts: DomNode[]?
//      Array of <script type="dojo/*"> DOMNodes.  If not specified, will search for <script> tags inside node.

I think the literal "<script..." is valid syntax since this is markdown, not HTML. However, the parser doesn't double-encode the value, so we end up with

<summary>&lt;p>Array of &lt;script type=&quot;dojo/*&quot;> DOMNodes.

which means the value of the summary node evaluates to

<p>Array of <script type="dojo/*"> DOMNodes. ...

rather than what we want:

<p>Array of &lt;script type="dojo/*"&gt; DOMNodes. ...

cc @kitsonk

Create an exporter that outputs a beautiful tree of HTML.

Check to see if the given value for a resolved type has a relatedModule and if it does, update the type to be an AMD MID in the output and do not inline. Otherwise, continue inlining as normal.

The parser is failing on this code in dijit.Declaration:

declare(..., { ...
mixins: [],
...
buildRendering: function(){
this.mixins = this.mixins.length ? ...
});

It doesn't like this.mixins.length since it thinks that this.mixins is null. Not sure how to deal w/that, other than rewriting it like:

        if(this.mixins.length){
            this.mixins = array.map(this.mixins, function(name){ return lang.getObject(name); } );
        }else{
            this.mixins = [ _Widget, _TemplatedMixin, _WidgetsInTemplateMixin ];
        }

The stack trace is:

ERR: dijit/t.js:72:31 TypeError: Cannot convert null to object
at Value.getProperty (/Volumes/Data/workspace/docparse/lib/Value.js:181:33)
at Scope.getVariable (/Volumes/Data/workspace/docparse/lib/Scope.js:177:25)
at Object.MemberExpression (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:607:59)
at read (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:239:27)
at Object.readBinaryExpression (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:189:15)
at read (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:239:27)
at Object.ConditionalExpression (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:395:15)
at read (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:239:27)
at Object.AssignmentExpression (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:247:16)
at read (/Volumes/Data/workspace/docparse/lib/esprimaParser.js:239:27)

In previous iterations of the parser/viewer, djConfig was handled as a "special case" object in an attempt to make it clear what various configuration options are available to a user. The problem with it was that lots of various configuration options were attached to different references of the same object; for instance, there may have been "isDebug" attached to djConfig, while other options may have been attached to dojo.config later on in code--which itself was just a reference to djConfig (if it existed).

I'm not sure how we should handle djConfig et al, but it will be a definite requirement for viewing 1.8+ API documentation. This ticket is here to keep a reference for that discussion/solution.

dijit/form/TextBox's module level summary is:

var TextBox = declare("dijit.form.TextBox", [_FormValueWidget, _TextBoxMixin], {
    // summary:
    //      A base class for textbox form inputs

However, it's appearing in the API viewer (and presumably the details.xml) as the summary from a property of InlineEditBox whose value is TextBox:

    // editor: String|Function
    //      MID (ex: "dijit/form/TextBox") or constructor for editor widget
    editor: TextBox,

See dojo/Declare.js. It declares methods from the constructor rather than in a prototype:

this.progress = function(update, /*Boolean?*/ strict){
    // summary:
    //      Emit a progress update on the deferred.
    // returns: dojo/promise/Promise
    //      Returns the original promise for the deferred.
    //
    // update:
    //      The progress update
    // strict:
    //      If strict, will throw an error if the deferred is already fulfilled.
    if(!fulfilled){
...

None of that information is showing up in the API output, it just has

<method name="progress" scope="prototype" type="function" from="dojo/Deferred">
<parameters/>
<return-types/>
</method>

Using a [private] flag on a property, its type unexpectedly changes in the generated XML.

Found the following cases (tested with a freshly updated js-doc-parse):
1/ type="Object" becomes type="null" by adding [private] to a property initialized at null.
2/ type="Object" becomes type="object" by adding [private] to a property initialized at {}.
3/ type="Number" becomes type="number" by adding [private] to a property initialized at some numeric value.

The piece of JS I used for testing (property declarations in a class, for each case with and without the [private] tag):

// prop1: Number
//      This is a property.
prop1: 1,

// prop2: [private] Number
//      This is a property.
prop2: 1,

// prop3: Object
//      This is a property.
prop3: null,

// prop4: [private] Object
//      This is a property.
prop4: null,

// prop5: Object
//      This is a property.
prop5: {},

// prop6: [private] Object
//      This is a property.
prop6: {},

The XML generated by js-doc-parse (freshly updated today) contains:

<property name="prop1" scope="prototype" type="Number" from="parsetest/ParseTest">
<summary>&lt;p>This is a property.&lt;/p></summary></property>

<property name="prop2" scope="prototype" type="number" from="parsetest/ParseTest" private="true">
<summary>&lt;p>This is a property.&lt;/p></summary></property>

<property name="prop3" scope="prototype" type="Object" from="parsetest/ParseTest">
<summary>&lt;p>This is a property.&lt;/p></summary></property>

<property name="prop4" scope="prototype" type="null" from="parsetest/ParseTest" private="true">
<summary>&lt;p>This is another property.&lt;/p></summary></property>

<property name="prop5" scope="prototype" type="Object" from="parsetest/ParseTest">
<summary>&lt;p>This is a property.&lt;/p></summary></property>

<property name="prop6" scope="prototype" type="object" from="parsetest/ParseTest" private="true">
<summary>&lt;p>This is a property.&lt;/p></summary></property>

If I run

$ ./parse.sh ../trunk/dijit/form/NumberTextBox.js

I get this strange output listing the return-type from number.js's regexp() function as "example:"

<method name="regexp" scope="normal" type="function" from="dojo/number">
<parameters>
<parameter name="options" type="Object" usage="optional">
<description>
<p>An object with the following properties: </p> <ul> <li><p>type (String, optional): <p>choose a format type based on the locale from the following: decimal, scientific (not yet supported), percent, currency. decimal by default.</p></p> </li> <li><p>pattern</p> </li> <li>type</li> <li>locale</li> <li>strict</li> <li>places</li> </ul>
</description>
</parameter>
</parameters>
<return-types>
<return-type type="example:"/>
</return-types>
<summary><p>Builds the regular needed to parse a number</p></summary>
<description>
<p>Returns regular expression with positive and negative match, group and decimal separators</p>
</description>
</method>

Strangely it doesn't happen when parsing number.js stand alone.

From dijit/_WidgetBase.js, the [const] on:

// id: [const] String
//      A unique, opaque ID string that can be assigned by users or by the
//      system. If the developer passes an ID which is known not to be
//      unique, the specified ID is ignored and the system-generated ID is
//      used instead.
id: "",
_setIdAttr: "domNode",  // to copy to this.domNode even for auto-generated id's

does not seem to get picked up. Output is:

<property name="id" scope="prototype" type="string" from="dijit/_WidgetBase">
<summary>
A unique, opaque ID string that can be assigned by users or by the system. If the developer passes an ID 
which is known not to be unique, the specified ID is ignored and the system-generated ID is used instead.
</summary>
</property>

Same for [readonly], [protected], etc., on srcNodeRef and baseClass.

In dojo/_base/xhr.js, __IoCallbackArgs is defined as:

    dojo.__IoCallbackArgs = function(args, xhr, url, query, handleAs, id, canDelete, json){
        // args: Object
        //      the original object argument to the IO call.
        // xhr: XMLHttpRequest
        //      For XMLHttpRequest calls only, the
        //      XMLHttpRequest object that was used for the
        //      request.
        // url: String
        //      The final URL used for the call. Many times it
        //      will be different than the original args.url
        //      value.
        // query: String
        //      For non-GET requests, the
        //      name1=value1&name2=value2 parameters sent up in
        //      the request.
        // handleAs: String
        //      The final indicator on how the response will be
        //      handled.
        // id: String
        //      For dojo.io.script calls only, the internal
        //      script ID used for the request.
        // canDelete: Boolean
        //      For dojo.io.script calls only, indicates
        //      whether the script tag that represents the
        //      request can be deleted after callbacks have
        //      been called. Used internally to know when
        //      cleanup can happen on JSONP-type requests.
        // json: Object
        //      For dojo.io.script calls only: holds the JSON
        //      response for JSONP-type requests. Used
        //      internally to hold on to the JSON responses.
        //      You should not need to access it directly --
        //      the same object should be passed to the success
        //      callbacks directly.
        this.args = args;
        this.xhr = xhr;
        this.url = url;
        this.query = query;
        this.handleAs = handleAs;
        this.id = id;
        this.canDelete = canDelete;
        this.json = json;
    };

and then referenced for the ioArgs parameter:

    dojo._ioAddQueryToUrl = function(/*dojo.__IoCallbackArgs*/ioArgs){
        //summary: Adds query params discovered by the io deferred construction to the URL.
        //Only use this for operations which are fundamentally GET-type operations.
        if(ioArgs.query.length){
            ioArgs.url += (ioArgs.url.indexOf("?") == -1 ? "?" : "&") + ioArgs.query;
            ioArgs.query = null;
        }
    };

However, that shows the parser thinks that __IoCallbackArgs doesn't have any attributes:

<method name="_ioAddQueryToUrl" scope="normal" type="function" from="dojo/_base/xhr">
<parameters>
<parameter name="ioArgs" type="Object" usage="required">
<description><p>An object with the following properties: </p></description>
</parameter>
</parameters>

Seems that "open" and "duration" aren't showing up in the doc for dijit/_WidgetBase:

./parse.sh ../trunk/dijit/_WidgetBase.js 2>warnings.txt |sed -n '/<javascript/,$p' > WidgetBase.xml

Methods have various tags, for example in _WidgetBase.js:

postMixInProperties: function(){
    // summary:
    //      Called after the parameters to the widget have been read-in,
    //      but before the widget template is instantiated. Especially
    //      useful to set properties that are referenced in the widget
    //      template.
    // tags:
    //      protected
},

They are not being picked up, except for private (#14), but they should be. According to dojo's code base and it's style guide (http://livedocs.dojotoolkit.org/util/doctools/markup#tags) all tags are supposed to work.

In the old Dojo 1.6 API doc, a method override having no doc comments in its source code used to get the doc from the parent class. An example:
http://dojotoolkit.org/api/1.6/dojox/mobile/View#buildRendering
In the XML generated nowadays for such overrides there is no documentation.

Will the doc inheritance be done at the level of XML to HTML conversion? Or will this be fixed at the XML level?
This is important for us to know, because we have to make the choice to either keep our overrides without any doc and count on the inheritance, or to duplicate doc pieces for all our overrides currently with no doc.

Although dojodoc format allows methods and classes to have both summaries and descriptions, scalar parameters and properties just have summaries, listed like

// foo: Number
//      There's no summary keyword but this is the summary
foo: 0

(where the above example could be either a foo parameter to a function, or a foo property of a class)

However ,when kwArgs gets inlined (ex: charting/action2d/PlotAction's constructor, third parameter), the parameter or property ends up with both a summary and description:

<parameter name="kwargs" type="Object" usage="optional">
<summary><p>Optional arguments for the action.</p></summary>
<description>
<p>An object with the following properties: </p> <ul> <li><p>duration (Number, optional): <p>The amount of time in milliseconds for an animation to last. Default is 400.</p></p> </li> <li><p>easing</p> </li> </ul>
</description>
</parameter>

The api-viewer is just displaying the summary, losing all that essential info from the descriptoin. I could change it to print both summary and description, but perhaps instead the exporter should shove all the information into the summary?

cc @cjolif

See also wkeese/old-api-viewer#16.

The code below uses lang.extend() rather than dojo.declare() to create a "class":

define([
    "dojo/_base/lang"
], function(lang){
    return lang.extend(function(){
        // summary:
        //      The constructor
    }, {
        // summary:
        //      The prototype
        func: function(a, b, c){
            // summary:
            //      The function
        }
    })
});

The parsed output is:

<object location="dojox/dtl/bill" type="function">
<properties/>
<methods>
<method name="constructor" scope="prototype" type="function" from="dojox/dtl/bill">
<parameters/>
<return-types/>
<summary><p>The constructor</p></summary>
</method>
<method name="func" scope="prototype" type="function" from="dojox/dtl/bill">
<parameters>
<parameter name="a" type="undefined" usage="required"/>
<parameter name="b" type="undefined" usage="required"/>
<parameter name="c" type="undefined" usage="required"/>
</parameters>
<return-types/>
<summary><p>The function</p></summary>
</method>
</methods>
<parameters/>
<return-types/>
<summary><p>The constructor</p></summary>
</object>

The parser clearly recognizes this as class-like at some level, hence the faux constructor method.

However, the object is marked as type="function". I would expect type="constructor" classlike="true".

While the user is able to see the deprecation information in the console at runtime (but not by default...), the information is missing in the API doc. It would be nice to introduce doc tags for this purpose.
However, a simple "deprecated" tag wouldn't be enough, it would need to be enriched with the deprecation hints (the arguments of dojo/_base/kernel.deprecated).

If there is a constructor, etc. and it has empty metadata summary/description, walk the prototype chain to try to find a parent object that has those filled out.

When running the parser on dojox/dgauges, the summary of the property dojox/dgauges/LinearScaler.minorTickInterval is correct.

But when running the parser on dojox, the summary of this property is replaced by the summary of dojox/Treemap.labelThreshold...

For dijit/form/_CurrencyTextBox, __Constraints is defined as a local variable:

/*=====
var __Constraints = declare([NumberTextBox.__Constraints, currency.__FormatOptions, currency.__ParseOptions], {
    // summary:
    //      Specifies both the rules on valid/invalid values (minimum, maximum,
    //      number of required decimal places), and also formatting options for
    //      displaying the value when the field is not focused (currency symbol,
    //      etc.)
    // description:
    //      Follows the pattern of `dijit.form.NumberTextBox.constraints`.
    //      In general developers won't need to set this parameter
    // example:
    //      To ensure that the user types in the cents (for example, 1.00 instead of just 1):
    //  |       {fractional:true}
});
=====*/

Therefore, when that type definition is used:

/*=====
// constraints: __Constraints
//      Despite the name, this parameter specifies both constraints on the input
//      (including minimum/maximum allowed values) as well as
//      formatting options.
constraints: {},
======*/

It's supposed to be inlined into a UL LI ... type list in the description, right? It's not:

<property name="constraints" scope="prototype" type="__Constraints" from="dijit/form/CurrencyTextBox">
<summary>
Despite the name, this parameter specifies both constraints on the input (including minimum/maximum allowed values)
 as well as formatting options.
</summary>
</property>

See for example dojox/charting/action2d/Highlight the kwArgs param of the ctor is optional: __XXXCtorArg? and just making it optional breaks the inlining mechanism.

Sometimes the vertical bars end up in the XML output file

For example, when parsing dojo/_base/window.js, the definition for doc:

/*=====
doc: {
    // summary:
    //      Alias for the current document. 'doc' can be modified
    //      for temporary context shifting. See also withDoc().
    // description:
    //      Use this rather than referring to 'window.document' to ensure your code runs
    //      correctly in managed contexts.
    // example:
    //  |   n.appendChild(dojo.doc.createElement('div'));
},
=====*/

It turns into:

<property name="doc" scope="normal" type="object" from="dojo/_base/window">
<summary>
Alias for the current document. 'doc' can be modified for temporary context shifting. See also withDoc().
</summary>
<description>
<p>Use this rather than referring to &#39;window.document&#39; to ensure your code runs correctly in managed contexts.</p>
</description>
<examples>
<example>
<p>| n.appendChild(dojo.doc.createElement(&#39;div&#39;));</p>
</example>
</examples>
</property>

Also some output from the Deferred modules:

<example>
<p>Deferred objects are often used when making code asynchronous. It may be easiest to write functions in a synchronous 
manner and then split code using a deferred to trigger a response to a long-lived operation. For example, instead of
 register a callback function to denote when a rendering operation completes, the function can simply return a deferred: </p>
 <p></p> <pre><code> // callback style: function renderLotsOfData(data, callback){ var success = false try{ for(var x in data){ 
renderDataitem(data[x]); } success = true; }catch(e){ } if(callback){ callback(success); } }</code></pre>
 <p></p> 
<p>| // using callback style | renderLotsOfData(someDataObj, function(success){
 | // handles success or failure | if(!success){ | promptUserToRecover(); | } | });
 | // NOTE: no way to add another callback here!!</p>
</example>

cc @ttrenka