__doc__ for functions, classes, objects etc.

[Dmitry Soshnikov]

On 03.09.2011 3:07, Brendan Eich wrote:
> On Sep 2, 2011, at 3:55 PM, Oliver Hunt wrote:
>
>> Function.toString isn't standardised, and I recall that in the past SM did elide dead code, multiple engines reformat code, so in general this doesnt seem reliable at a library level.  It also doesn't work for builtin functions, and I feel we'd want a solution that allows documentation for builtin functions as well.
> Oh sure, Irakli is just making do with what happens to work. SpiderMonkey doesn't do source recovery, so it needs something special and the label hack Irakli found is "it" (for now!).
>
> This thread was about standardizing something guaranteed that does not depend on toString, but we would love to have a winning library approach whose API we can standardize. Such a library could be scrappy (I hope not crappy ;-) about using "what happens to work" on particular engines and even versions.
>
>

If it had been the main goal, I wouldn't start the topic. Because I 
remember perfectly we already found before several hacks which "just 
work" right now in all (modern) engines. One of those:

function foo(x, y) {
   var __doc__ = " ... ";
}

though, of course places additional variable inside. However, from this 
viewpoint it doesn't matter about what developers will deal -- whether 
to write doc: " ..." | " ..." | " ..." or var __doc__ = " ...". 
Completely doesn't matter. Since if they deal, they will just use an 
approach without worrying that e.g. name __doc__ can be used inside. It 
can't if the deal.

So all these hacks are fine for ad-hoc local experiments. Though, of 
course may lead to wide-spreading. In this case we should think which 
format of a documentation is better to chose (will you explain later why 
so "strange" syntactic form of a doc-string was chosen  -- that's 
because we couldn't find better "hack" when designing a "library"?).

Considered JavaDoc that's said would "just work" for tones of old code 
and automatically get support of the documentation and type-guards. 
OTOH, non-comment docs (such as vars or lables) allow not to worry about 
minifiers which won't remove them. But from this viewpoint it again 
doesn't matter how to leave this doc-string in the source code -- either 
with an option of a minifier or with a non-doc construct which will be 
skipped.

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

If course we don't plan to include the feature for standardization (as 
Oliver noted; though, I'm not sure he worked with Python and couldn't 
appreciate its simplicity of getting the documentation on exactly 
*built-ins* and also frameworks), they yes -- it can be a simple ad-hoc 
library for local projects (because it will be hard to switch people 
from used JavaDocs to "hack"-versions of documentation; besides, an old 
code no one will want to rewrite for this).

Dmitry.

>> This shouldn't be taken as support for this idea (documentation as part of the language) as I feel that this is the type of feature i'd associate with the development environment rather than part of the language.
> That's the other thing about a library approach: it doesn't need to land in language, but then the IDE may have to grow a full parser (probably good IDEs already have one).
>
> /be
>
> _______________________________________________
> es-discuss mailing list
> es-discuss at mozilla.org
> https://mail.mozilla.org/listinfo/es-discuss