__doc__ for functions, classes, objects etc.

Dmitry Soshnikov dmitry.soshnikov at gmail.com
Tue Sep 6 13:52:52 PDT 2011


On 04.09.2011 0:31, Brendan Eich wrote:
> On Sep 6, 2011, at 12:36 AM, Dmitry Soshnikov wrote:
>
>> So, IMO we can't build a "library on hacks" which we then standardize. If to implement, then the best approach at the lower level, as Python did (with processing at compilation time).
> I see no reason why we can't build up a library or competing libraries first, then standardize. Sure, it would be easier for the library implementors if there were standard low-level doc-string or doc-comment (or doc-data as Allen just posted) plumbing.
>
> But JS can host all sorts of hacks to front a uniform cross-browser/version API -- this has been going on at least since the "Ajax" days.
>
> The hard thing about standardizing first is that TC39 won't do as good a job as competing library authors contending for users, but TC39 de-jure standardization will result in everyone being stuck with whatever we invent.
>

Sure, it's true, the way "to standardize de-facto things" is very 
efficient and practical. Though, sometimes without low-level resources 
it's not always possible to implement a library in an elegant way. And 
to standardize "hacks"... don't know. Not sure it's the best idea.

> Did you have a concrete lower-level suggestion that does not depend on normative language prohibiting dead code elimination combined with Function.prototype.toString() standardization?
>

I have several concrete lower-level proposals:

(1) to standardize `toString` (for this particular case -- do not remove 
comments inside);

If the (1) is not possible (why by the way?), 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 () { ... })

(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

Dmitry.


More information about the es-discuss mailing list