split up dojo namespace in meaningful sub-sections in API docs

[mikewse]

Dojo's generated API docs have a huge section for the dojo root namespace at http://api.dojotoolkit.org/jsdoc/dojo/HEAD/dojo and this becomes a bit hard to overview.

It would be great if this could somehow be split up in logical sections to easier find your way around it. Possible alternatives for splitting could be f ex augmenting the namespace based categories with sub-sections based on source file:

dojo:
  (connect.js)
  (declare.js)
dojo.back:
dojo.cldr:
...

or adding some special parser tag to be able to add categorization information to each file or function and use those headings in the docs:

dojo.declare = ...
  // @category=Object-Oriented Class Support
  // ...
->
dojo:
  (Object-Oriented Class Support)
dojo.back:
...

[peller]

I think we had some sort of 'tags' at one point proposed for this?

[dante]

we did. bill - you were conceiving a list of potential tags you wanted to use throughout dijit, like "private" "protected" etc, and that format was going to be expanded into something usable generically, so we could group them in templates in jsdoc.

tags here are important, and keeping concepts grouped together would help overall in documenting the toolkit effectively. (note: we are already doing this manually in the quickstart/ section of the wiki docs)