When the `help` function is called on the F object, the
following steps are taken:
1. If [[Class]] of the function is not "Function" throw TypeError
2. Let doc be [[Documentation]] property of F
2.1 If doc is `undefined` return empty string
2.2. return String(doc)
It's a simplified version of course (moreover, Allen wanted
to eliminate [[Class]], so -- it's just an example).
Do we need this?
Dmitry.
On 09.08.2011 23:59, Dmitry A. Soshnikov wrote:
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.
_______________________________________________
es-discuss mailing list
[email protected] <mailto:[email protected]>
https://mail.mozilla.org/listinfo/es-discuss
