Opened 13 years ago

Closed 11 years ago

#2172 closed defect (fixed)

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

Reported by: skinner Owned by: Neil Roberts
Priority: high Milestone: 1.1
Component: Doc parser Version: 0.4.1
Keywords: Cc:
Blocked By: Blocking:

Description (last modified by 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:

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

Change History (4)

comment:1 Changed 12 years ago by skinner

Description: modified (diff)

comment:2 Changed 12 years ago by owen

Owner: changed from owen to Neil Roberts

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. ???

comment:3 Changed 12 years ago by dante

Milestone: 1.1
Priority: normalhigh
severity: normalmajor

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

comment:4 Changed 11 years ago by Neil Roberts

Resolution: fixed
Status: newclosed

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

Note: See TracTickets for help on using tickets.