__doc__ for functions, classes, objects etc.

[Brendan Eich]

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.

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.


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

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?

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.

/be