__doc__ for functions, classes, objects etc.

[Dmitry Soshnikov]

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.