On 04.09.2011 23:45, Brendan Eich wrote:
On Sep 6, 2011, at 1:52 PM, Dmitry Soshnikov wrote:
(1) to standardize `toString` (for this particular case -- do not remove
comments inside);
If the (1) is not possible (why by the way?),
Because comments are not saved in the compilation process and doing so would
slow parsing down and take more space. It's not obvious this would matter in
head-to-head competition with other browsers (esp. with minified benchmarks) --
we would have to find out.
Switching to source recovery will entrain more space but may be tolerable --
except that switching to source recovery is work, competing with other demands.
There's no free lunch.
Anyway, that is the SpiderMonkey perspective. I'm not sure about Rhino or other
engines that do not already retain the source buffer rather than implement a
decompiler.
Yes, thanks; sounds logical and quite obvious. Though, one can save only
doc-comment at compilation; not all.
At a higher level, ECMA-262 has underspecified Function.prototype.toString
forever. Jumping to the other extreme when there's a simpler and more direct
solution seems like a mistake.
Well, then we don't have a reliable way of implementing such a runtime
library -- no matter how syntactically to represent the documentation:
vars, labels, "labels aks JSON", etc -- if some implementation is
allowed to return any result in `toString` decompilation, we can't be
sure. But, for such implementation we may simply show "No documentation
is available" of course, which will be a signal to fix an implementation
then -- in case if a feature is wide-spread.
then we can:
(2) either to change grammar for function declarations/expression (to add
Documentation production before the `function` token; though, not so convinient
for FE, when e.g. foo: function () { ... })
I'm not sure what you mean in that parenthetical aside.
I meant grammar for function declarations -- to add optional
`Documentation` production.
FunctionDeclaration :
Documentation<opt> function Identifier ( FormalParameterListopt ) {
FunctionBody }
where Documentation is /* doc string */
However, it's just a variant. That's said, it's not so easy to catch
function expressions in this way, but they are also need somehow to be
documented.
var foo = {
/**
* my funciton
*/
bar: function () { ... }
}
on typing `help(foo.bar)` I'd like to see "/**\n* my function\n*/", but
it's not obvious for grammar at all. Moreover, a function can be
assigned to a property (being defined in completely different syntactic
position).
From this viewpoint of course _inner_ comments (from which I actually
started the topic showing Python's triple-doc-strings inside methods) is
better. This approach even allow not to define own __doc__ property, but
place internal method on `Function.prototype` and activation get
`this.[[Doc]]`.
All discussed "hacks" -- var __doc__ = " ...", or label doc: " ..." are
fine. Though if we had have `toString`'s guarantee it would be even better.
We could say something much simpler, e.g. any labeled expression statement in
prologue position must be retained (by whatever means) such that it appears in
the toString result for the function containing that prologue.
Maybe. But the main thing -- is a _convenience_ of a programmer. An
application, practical programmer should type less, do more. In the best
variant, old code should just work also. I switched to JavaDocs since,
as mentioned, many of source are written using it (though, initially
talked about inner-docs). If we can provide a convenient way of
describing docs, as I said, _exact syntax_ is not so essential for me;
the convenient feature -- that's what is essential.
Simpler specs that do not imply one and only one implementation technique are
usually better.
(3) make a pre-parsing of doc-comments and to inject them as a properties of
functions. I gave an example of such a pre-processor (just a small prototype,
but it can generate the docs and type-guards) -- https://gist.github.com/1186853
How would this be part of the standard?
No, not this; this is just a prototype. Though, it relates to (1) -- an
optional `Documentation` non-terminal for FD, which is just parsed.
However, that's said, it's hard for FE, so I don't completely like it
yet -- just wanted to provide a variant which would support all old code
also.
Remember browsers are not IDEs. They have to load code, including some
comments, very quickly. They currently either parse and drop comments (which
lexically are space) on the floor, or else retain whole source buffers or
slices of source buffers for F.p.toString. TC39 is not going to add overhead to
this process lightly.
OK, I understand and think it's sensible. And as I mentioned in previous
letter, I'd better recommend the feature to Node.js _only_ for now. Not
to ECMAScript. Since the most use-cases are related with Node's console.
Dmitry.
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
