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
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
