[api ref] dojo.data methods do not show up in API reference

[skinner]

Most of the dojo.data files have doc comments, but those doc comments don't show up in the API reference page.

For example, here's the dojo.data.core.Read source code, which has 10 methods with comments:

• http://archive.dojotoolkit.org/nightly/src/data/core/Read.js

And here's the API reference page for dojo.data.core.Read, which does not show any of the 10 methods, or their comments:

• http://dojotoolkit.org/api/#dojo.data.core.Read

[owen]

Neil, this seems to be a parser issue. Dojo.data.core.read.getValue is defined so:

	getValue: function(/* item */ item, /* attribute || attribute-name-string */ attribute, /* value? */ defaultValue) {
		/* summary:
		 *   Returns a single attribute value.
		 *   Returns defaultValue if and only if *item* does not have a value for *attribute*.
		 *   Returns null if and only if null was explicitly set as the attribute value.
		 *   Returns undefined if and only if the item does not have a value for the given 
		 *   attribute (which is the same as saying the item does not have the attribute). 
		 * description:
		 *   Saying that an "item x does not have a value for an attribute y"
		 *   is identical to saying that an "item x does not have attribute y". 
		 *   It is an oxymoron to say "that attribute is present but has no values" 
		 *   or "the item has that attribute but does not have any attribute values".
		 *   If store.hasAttribute(item, attribute) returns false, then
		 *   store.getValue(item, attribute) will return undefined.
		 */
		 
		/* exceptions:
		 *   Conforming implementations should throw an exception if *item* is not
		 *   an item, or *attribute* is neither an attribute object or a string.
		 * examples:
		 *   var darthVader = store.getValue(lukeSkywalker, "father");
		 */
		dojo.unimplemented('dojo.data.core.Read.getValue');
		var attributeValue = null;
		return attributeValue; // a literal, an item, null, or undefined (never an array)
	},

and the XML output is so:

<function name="dojo.data.core.Read.getValue" prototype="dojo.data.core.Read">
   <returns type="a literal, an item, null, or undefined (never an array)"/>
     <summary>exceptions:</summary>
     <parameters>
        <parameter name="item" type="item"/>
        <parameter name="attribute" type="attribute || attribute-name-string"/>
        <parameter name="defaultValue" optional="true" type="value"/>
    </parameters>
</function>

So the "summary:" seems to be getting knocked out by the "exceptions:" block. ???

[dante]

coincidentally, the dojo data api now produces this output, 9 months later:

    * warning: Invalid argument supplied for foreach() in /var/www/html/modules/node/node.module on line 521.
    * warning: implode() [function.implode]: Bad arguments. in /var/www/html/modules/node/node.module on line 525.
    * user warning: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '' at line 1 query: SELECT n.nid, n.vid, n.type, n.status, n.created, n.changed, n.comment, n.promote, n.sticky, r.timestamp AS revision_timestamp, r.title, r.body, r.teaser, r.log, r.format, u.uid, u.name, u.picture, u.data FROM node n INNER JOIN users u ON u.uid = n.uid INNER JOIN node_revisions r ON r.vid = n.vid WHERE in /var/www/html/includes/database.mysql.inc on line 172.

when viewing the page:

http://redesign.dojotoolkit.org/?q=jsdoc/dojo/HEAD/object/dojo.data.api.Read

[pottedmeat]

(In [12620]) Fixes #2172. Edited summary lines that started with a parameter name.