__doc__ for functions, classes, objects etc.
brendan at mozilla.com
Tue Aug 23 09:54:17 PDT 2011
A convenient notation for multiline documentation comments, with convenient reflection (*not* via toString() scraping!), would be a fine thing.
Some of the design dimensions:
0. Comment vs. string / quasiliteral?
1. function-only, or object literal too -- or any declaration?
2. Before function, a la javadoc comments, or first thing in body, a la the prologue directive idea?
3. Reflected via function .doc property, a Function.extractDocComment static method, or something even more mirror-like/stratified?
I'm not sure what is best, I lack experience programming in languages with doc-comment or triple-quoted equivalents (Python attached tests, e.g.). Comments (heh) welcome.
Thinking about 1, I would start with function-only.
For 2 I'm inclined to say "in body" because it's too easy to lose the "before" context during the life of a function, compared to losing part of the body by accident.
Regarding 3, I bet Function.extractDocComment or a better name wins, especially if the whole solution allows monkey-patching a polyfill for downrev browsers that support source recovery (not SpiderMonkey's decompiler).
More information about the es-discuss