Right. And this is where Python just wins. In respect of bult-ins and
methods provided by framework authors. That's said in the initial
letter, we can always go to the language documentation website and read
it, but to the help "in-place" seems much better.
Though, there is another issue here (beside the source- and byte- code
size increasing). The "offline" documentation embedded inside the
function objects may become obsolete, while the online is up-to-date.
But, for the specified built-ins it's not the case, since the spec
doesn't change too often. And regarding user-defined framework codes,
anyway the code is parsed each time -- it is the property and the deal
of the JS engine to correctly parse doc-comment and assign it as a
property to a function. That is, the documentation may change in-time
and if you use external script file, then you always have up-to-date
documentation.
Dmitry.
On 30.08.2011 20:09, Dave Fugate wrote:
This feature is particularly useful for /framework/ authors and their
users. Countless times I've found myself using a browser's console
debugging tool to figure out why something's busted. In these cases,
I nearly always resort to navigating to some JS framework's website
for their documentation or scrutinizing their code directly to figure
out what's going wrong. If I could just call
'printHelp(xyz....someMethod)', less of my time would be used. The
other bit of utility here is that framework documentation can live
side-by-side with the code and be automatically generated from it
(e.g., http://pydoc.org/2.5.1/timeit.html) as opposed to maintaining
it separately. A very useful feature to have from my Python-biased
perspectiveJ
My best,
Dave
*From:*[email protected]
[mailto:[email protected]] *On Behalf Of *Dmitry A. Soshnikov
*Sent:* Tuesday, August 30, 2011 7:42 AM
*To:* Rick Waldron
*Cc:* Brendan Eich; es-discuss Steen
*Subject:* Re: __doc__ for functions, classes, objects etc.
On 30.08.2011 17:41, Rick Waldron wrote:
On Tue, Aug 30, 2011 at 3:39 AM, Dmitry A. Soshnikov
<[email protected] <mailto:[email protected]>> wrote:
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)
A built-in, global object function property named "help()" will no
doubt conflict with userland code
It's derived question, we may choose any name which fits well (though,
IMO `help` name isn't used much). The main thing I want to clarify at
this step, whether we need at all this thing in ES?
Since committee keeps silence, I'd like to consider it better as "Yes,
we need it and there is nothing to add", rather than "We don't need
and don't want even to discuss" (since there is no big sense in later,
because the functionality seems useful). However, we need to clarify
how *exactly* it's useful. Maybe using JS in console is so rare case
and it isn't required much. OTOH, era of client-side-only-JS is behind
and JS is also on server now. And from this viewpoint, in the console,
it's the best to get the help, hints for parameters and even type
checking for functions.
So, what should I do to apply the first meaning?
Dmitry.
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
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
