OK, let's up the topic. Seems there are no technical issues in the
proposed thing -- we can simply either accept it or not. The question is
whether it's needed and sound proposal and the feature to have in
ECMAScript.
Some summarized features below:
+ Ability to get help of any built-in and any user-defined function
directly in runtime (in later case, authors should provide the
documentations though)
+ Auto-suggest and hints of parameters and their types when typing
function name in console.
+ Ability even to have sort of guards for types with issuing warnings in
case if types mismatch (sort of recent contract.coffee projects and
actually other langs, e.g. Haskell, Erlang, etc).
- Code size will be increased to store the doc string. This can be
optional in case of minimized scripts (lint tools can have option
"Remove doc-comments")
As an example I show a spec description for `parseInt` function:
15.1.2.2 parseInt (string , radix)
Let [[Documentation]] property of the `parseInt` function be the
following string:
"The parseInt function produces an integer value dictated by
interpretation of the contents of the string argument according to the
specified radix. Leading white space in string is ignored. If radix is
undefined or 0, it is assumed to be 10 except when the number begins
with the character pairs 0x or 0X, in which case a radix of 16 is
assumed. If radix is 16, number may also optionally begin with the
character pairs 0x or 0X."
...
x.x.xx help(F)
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]
https://mail.mozilla.org/listinfo/es-discuss
