__doc__ for functions, classes, objects etc.

Brendan Eich 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).

/be


More information about the es-discuss mailing list