#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 15 years ago by
Component: | General → Documentation |
---|
comment:2 Changed 14 years ago by
Cc: | [email protected]… added |
---|
comment:3 Changed 14 years ago by
Cc: | [email protected]… 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 14 years ago by
Milestone: | 0.4 → 0.4.1 |
---|
comment:5 Changed 14 years ago by
Milestone: | 0.4.1 → 0.5 |
---|---|
Priority: | normal → lowest |
I've yet to see this be necessary. If I hear complaining, I'll add it.
comment:6 Changed 13 years ago by
Milestone: | 1.0 → 1.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 13 years ago by
Cc: | skinner Adam Peller added; [email protected]… [email protected]… removed |
---|
comment:8 Changed 13 years ago by
comment:11 Changed 13 years ago by
comment:12 Changed 13 years ago by
comment:14 Changed 13 years ago by
Priority: | lowest → high |
---|
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 13 years ago by
comment:16 Changed 13 years ago by
Resolution: | → invalid |
---|---|
Status: | new → closed |
The documentation module now has no concept of packages, everything's done through namespace, which is easily documented.
Might also be nice to support module-level comments that appear in files with a format that looks like this: