Opened 13 years ago

Closed 12 years ago

Last modified 11 years ago

#982 closed task (invalid)

Provide package-level comment format

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

Description

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

Change History (17)

comment:1 Changed 13 years ago by Neil Roberts

Component: GeneralDocumentation

comment:2 Changed 13 years ago by skinner

Cc: skinner@… added

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.
        ...
    };
}();

comment:3 Changed 13 years ago by Adam Peller

Cc: peller@… added

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

comment:4 Changed 13 years ago by dylan

Milestone: 0.40.4.1

comment:5 Changed 13 years ago by Neil Roberts

Milestone: 0.4.10.5
Priority: normallowest

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

comment:6 Changed 12 years ago by Adam Peller

Milestone: 1.01.1

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.

comment:7 Changed 12 years ago by Adam Peller

Cc: skinner Adam Peller added; skinner@… peller@… removed

comment:8 Changed 12 years ago by Adam Peller

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

comment:9 Changed 12 years ago by dante

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

comment:10 Changed 12 years ago by Adam Peller

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

comment:11 Changed 12 years ago by Adam Peller

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

comment:12 Changed 12 years ago by Adam Peller

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

comment:13 Changed 12 years ago by Adam Peller

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

comment:14 Changed 12 years ago by dante

Priority: lowesthigh

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.

comment:15 Changed 12 years ago by dante

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

comment:16 Changed 12 years ago by Neil Roberts

Resolution: invalid
Status: newclosed

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

comment:17 Changed 11 years ago by Adam Peller

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

Note: See TracTickets for help on using tickets.