Opened 7 years ago

Closed 7 years ago

Last modified 7 years ago

#15650 closed enhancement (fixed)

Improving dojo/store API documentation for options

Reported by: dylan Owned by: Kris Zyp
Priority: blocker Milestone: 1.8
Component: Data Version: 1.7.3
Keywords: Cc:
Blocked By: Blocking:

Description

Two requests for improved API viewer information for Dojo Store:

"I'm looking for the possible options that a Store can receive (in my case dojo.store.Memory). Memory's doc says that it receives a dojo.store.api.Store.QueryOptions? but there's no documentation for that."

"In the examples for the various Store examples, a constructor is passed an object with initialization parameters. When I look at the documentation in the ""constructor"" method for JsonRest?, the parameter is ""options"" but nothing more. Where should I look for the list of permissible key/value pairs? (My html script is throwing a type error on the line with the JsonRest? constructor and I'm not sure why.)"

In both cases, the API docs and the reference guide don't really provide a list of what options are available

Change History (6)

comment:1 Changed 7 years ago by dylan

Milestone: tbd1.8
Priority: highblocker

comment:2 Changed 7 years ago by Kitson Kelly

Actually looking at this, the inline code documentation is right, but the problem is that the js-doc-parser is not mixing in the dojo/store/api/Store.js into the api.xml. Once that is pulled in, then a full set of documentation should appear in the API Viewer.

I will look into this further.

comment:3 Changed 7 years ago by Kitson Kelly

Opened js-doc-parse issue https://github.com/csnover/js-doc-parse/issues/64 to cover the API docs...

I will update the reference-guide further to reflect the dojo/store/api/Store though.

comment:4 Changed 7 years ago by bill

Resolution: fixed
Status: newclosed

In [29333]:

Use declare() for kwargs definitions involving inheritance, to workaround doc parser bug and to make it more obvious that these are classes, rather than plain functions. Fixes #15650.

comment:5 Changed 7 years ago by Kitson Kelly

Also did a significant overhaul of reference-guide: https://github.com/dojo/docs/commit/c57530d2e277371c41618887fcaa26729cc7f0f6

comment:6 Changed 7 years ago by bill

Note that the constructor's kwargs argument is now listed as type dojo/store/Memory or dojo/store/JsonRest, meaning that any of the properties of Memory or JsonRest can be specified to the constructor for those respective object (just like widgets, or declaratively created DOMNodes). It's probably quite confusing for someone reading the documentation.

Note: See TracTickets for help on using tickets.