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

[Mike Wilson]

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

[Adam 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)

[Neil Roberts]

We have tags and have been discussing adding categories. We need to bring this up in a meeting

[ben hockey]

i'm trying to identify stale tickets. if there is a need to keep this ticket open, please replace the "needsreview" keyword with "reviewed". if there is no need to keep this ticket open then please close it.

[bill]

The reference doc is already mostly updated to document functions per module (aka file).

The API documentation comments still need to be updated, or if we are optimistic, it will all be handled automatically by a new documentation parser from Rawld or Colin, plus perhaps some changes needed in the viewer too.

[bill]

Duplicate of #13101.