Provide package-level comment format

[Neil Roberts]

Should add the ability to put up a package-level summary in the first comment block of the file.

[skinner]

Might also be nice to support module-level comments that appear in files with a format that looks like this:

dojo.provide("dojo.foo.Bar");

dojo.foo.Bar = new function() {
/* The Bar package implements a variety of important
 * functions having to do with Bars and Bar-going.
 */
    this.doBarDance = function(/* string? */ danceName) {
        // Summary: Does a little dance.
        ...
    };
}();

[Adam Peller]

Comments probably belong at the top-level as they may or may not be a constructor function. Following the style of function docs, possible sections include: purpose, author(s)/owner(s), acknowledgements... ?

[Neil Roberts]

I've yet to see this be necessary. If I hear complaining, I'll add it.

[Adam Peller]

consider this a complaint :) I think it's valuable for a developer to be able to give certain information about why a module is organized like it is, and we should standardize on what that's supposed to look like. It may help a developer figure out how to find things if we could have a tool document the tree this way.

[Adam Peller]

(In [11695]) Move singleton docs inline, where possible. Fill in some missing summaries. Refs #982

[dante]

(In [11697]) refs #982 - package level sup docs for dojo

[Adam Peller]

(In [11698]) Fill in missing summary. Refs #982

[Adam Peller]

(In [11702]) Move supplemental docs to their respective projects. Refs #982

[Adam Peller]

(In [11705]) Move singleton docs inline, where possible. Refs #982

[Adam Peller]

(In [11706]) This file is for the doc system only. Refs #982

[dante]

I don't like the workaround we're using, and it didn't seem to work very well. Booleans being redeclared as objects, etc. Perhapds half of the checkins on this ticket still aren't being picked up.

I strongly propose a way to solve part of it: actual package-level-docs.

anything after a dojo.provide() in comments could be treated as a block:

dojo.provide("dojo.fx");
// summary: Additional Animations not in core

I argue it does not hinder readability (being in the first few lines of the .js), is immeasurably easier to maintain than dojo/resources/_modules.js with:

/*=======
dojo.fx = {
     // summary: foo
};
========*/

I would even argue dojo.provide()-level-comments are more readable than the above special comment block.

it obviously won't solve every instance where we need to attach information to an object (namespace, project, etc) but it would definately help. Also, the above metioned aspects about meta data being extracted from package-level comments (like code origins, alternate licencising, etc) it very possible with this format.

[dante]

(In [11793]) refs #982 - stack container code typo causing doc parser to skip inline documentation

[Neil Roberts]

The documentation module now has no concept of packages, everything's done through namespace, which is easily documented.

[Adam Peller]

(In [15202]) Correct iphone example. Refs #982