__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Tue Aug 9 12:59:55 PDT 2011


On 23.08.2011 20:54, Brendan Eich wrote:
> A convenient notation for multiline documentation comments, with convenient reflection (*not* via toString() scraping!), would be a fine thing.
>

Yes, exactly this -- help(...) function, and also good auto-complete of 
object methods helped me some time ago formerly to learn Python very 
quickly just playing with it in console. By the way, ECMAScript (who 
will take responsibility to implement the ECMAScript -- ethanol 
implementation? :)) also needs some installation binaries with the 
console. And yes -- with this great features for learning -- 
auto-complete of methods (the best thing to investigate objects just 
pressing `tab`) and help(...) function. I remember ES4 had/has the REPL, 
why not ES5? Of course we have all those consoles directly from the 
browsers (and also Node.js REPL), but it could be useful. Anyway, it's 
another topic, just relatively touches help(...) functions.

> Some of the design dimensions:
>
> 0. Comment vs. string / quasiliteral?
>
> 1. function-only, or object literal too -- or any declaration?

I think functions are the main case, yes. Not sure about literals, since 
there are open issues such as, "how to document a property" (via 
descriptor field?)?

> 2. Before function, a la javadoc comments, or first thing in body, a la the prologue directive idea?

That's said, if "before", then we should consider white-spaces and 
newlines after the comment and before the function header (though, as 
well as in the prologue). If "before", then tones of old code written in 
javadoc will just work with the new engine. OTOH, this means that the 
exact syntax of javadocs will be standardized at the level of the spec 
(and it's a sound thing -- people will have to write exactly e.g. 
@property that the "doc-er" catch it correctly. OTOH again -- why not? 
-- to standardize common syntax of documenting functions). However, the 
spec may not parse the exact content of the comment but just save it as 
a string, regardless of what is written insides.

A variant with "inside" is also good, underlines that the comment is 
sort of a function's "property" (I like yours simple "doc" name for 
that). Both variants are good, just "outside" has the advantage that the 
old code will just hook on it.

> 3. Reflected via function .doc property, a Function.extractDocComment static method, or something even more mirror-like/stratified?
>

Yes, both are fine, ".doc" is great. Perhaps, even global binding help(...).

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

Yes, this is the main case.

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

At first glance there should be no issues with parsing in both cases. We 
sure have to restrict that only the first multiline comment from _above_ 
of a function is treated as doc-comment. It will not touch any other 
upper-comments

// this one isn't caught

/*
and this one also
*/

/**
  * but this is OK
  */
function foo() {}

console.log(foo.doc); // "but this is OK"

With the prologue -- there also directives' places should be considered. 
I think the best place for them is under the doc-comment.

function foo() {

   "" My function """

   "use strict";
}

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

Yes, maybe.

Dmitry.



More information about the es-discuss mailing list