__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Wed Aug 31 01:35:08 PDT 2011

On 30.08.2011 19:33, Dean Landolt wrote:
> On Tue, Aug 30, 2011 at 10:41 AM, Dmitry A. Soshnikov 
> <dmitry.soshnikov at gmail.com <mailto:dmitry.soshnikov at gmail.com>> wrote:
>     On 30.08.2011 17:41, Rick Waldron wrote:
>>     On Tue, Aug 30, 2011 at 3:39 AM, Dmitry A. Soshnikov
>>     <dmitry.soshnikov at gmail.com <mailto:dmitry.soshnikov at gmail.com>>
>>     wrote:
>>         OK, let's up the topic. Seems there are no technical issues
>>         in the proposed thing -- we can simply either accept it or
>>         not. The question is whether it's needed and sound proposal
>>         and the feature to have in ECMAScript.
>>         Some summarized features below:
>>         + Ability to get help of any built-in and any user-defined
>>         function directly in runtime (in later case, authors should
>>         provide the documentations though)
>>         + Auto-suggest and hints of parameters and their types when
>>         typing function name in console.
>>         + Ability even to have sort of guards for types with issuing
>>         warnings in case if types mismatch (sort of recent
>>         contract.coffee projects and actually other langs, e.g.
>>         Haskell, Erlang, etc).
>>         - Code size will be increased to store the doc string. This
>>         can be optional in case of minimized scripts (lint tools can
>>         have option "Remove doc-comments")
>>         As an example I show a spec description for `parseInt` function:
>> parseInt (string , radix)
>>         Let [[Documentation]] property of the `parseInt` function be
>>         the following string:
>>         "The parseInt function produces an integer value dictated by
>>         interpretation of the contents of the string argument
>>         according to the specified radix. Leading white space in
>>         string is ignored. If radix is undefined or 0, it is assumed
>>         to be 10 except when the number begins with the character
>>         pairs 0x or 0X, in which case a radix of 16 is assumed. If
>>         radix is 16, number may also optionally begin with the
>>         character pairs 0x or 0X."
>>         ...
>>         x.x.xx help(F)
>>     A built-in, global object function property named "help()" will
>>     no doubt conflict with userland code
>     It's derived question, we may choose any name which fits well
>     (though, IMO `help` name isn't used much).
> That's tough to say for sure, and even if true still probably isn't 
> good enough. Regardless, there's no excuse for this kind of global, 
> especially in light of a module system. Sure, specifically in a repl 
> you'd probably want to skip the require -- for this node offers up 
> dot-prefixed repl keywords. So something like .help(F) would be a lot 
> safer and nearly as convenience as a help global.

Yes, I guess. Anyway, all this about only "debug-in-console" mode, so 
.help(...) would be just fine.

> I think it would be useful for the committee to weigh in on the idea 
> of repl plugins. This particular design is pretty nice but it 
> conflicts for statements beginning with non-zero-prefixed decimals. In 
> practice I don't see this causing any real problems, but it'd be great 
> if the grammer explicitly forbid this, effectively reserving it for 
> repl hooks.

Maybe, though, in contrast with other langs, ES is different since 
because of browser vendors has different implementations. Actually, 
there is no such implementation as "ECMAScript". In contrast, languages 
such as e.g. Python or Erlang have the sample implementations (usually 
that which is placed directly on the website of the language), and there 
of course the attention to a good console and downloadable and 
installable "in one click" REPLs is paid much. And that's said, this 
increases and speeds up the learning of the language. I don't know what 
to propose in case of ECMAScript, since repeat, there is no such 
language as ECMAScript "in real life" and therefore, there is no "the 
sample REPL" for which it would be the best to have .help(...) function 
which shows the doc-comment of a function.

And in case of a browser -- I don't think it's needed much. OTOH, of 
course devs. also debug the browser code in tools such as Firebug, where 
they also can use this .help(...).

So I'm still thinking myself, is it worth to move it to the level of the 
ES spec (the [[Doc]] property and similar) or it's not needed much and 
is only for "playing in console". OTOH, this "playing in console" is 
what makes Python the best in this respect.

>     The main thing I want to clarify at this step, whether we need at
>     all this thing in ES?
>     Since committee keeps silence, I'd like to consider it better as
>     "Yes, we need it and there is nothing to add", rather than "We
>     don't need and don't want even to discuss" (since there is no big
>     sense in later, because the functionality seems useful). However,
>     we need to clarify how *exactly* it's useful. Maybe using JS in
>     console is so rare case and it isn't required much. OTOH, era of
>     client-side-only-JS is behind and JS is also on server now. And
>     from this viewpoint, in the console, it's the best to get the
>     help, hints for parameters and even type checking for functions.
> Brenden weighed in and laid out some of the design space. I suspect 
> this functionality can largely be pieced together with what harmony 
> already gives us. As Brenden hinted, quasis give us multiline strings. 
> The __doc__ key is just screaming to be a private name instead 
> (generally true of all wunderbars IMHO). This could be tacked onto 
> functions and objects imperatively, but it would be pretty goofy to 
> put the doc string /after/ its function body. So for this to be 
> serviceable we'd need a declarative way to do this inside the function 
> body. ISTR some syntax being thrown around to set an own-prop on a 
> function from inside its body but I can't recall specifics -- is there 
> anything harmonious for this?
> Put the above three bits together with a de facto repl plugin syntax 
> and module mapping and you get a more sanitized (and extensible) 
> version of python's repl with the same developer ergonomics.

Yes, but all this needs to be considered as "needed" first. The lack 
which I mentioned myself of the feature is that the source code will be 
increased (lint tools though will provide "Remove doc-comments" for 
indemnified scripts) and the size of a byte-code to keep additional 
property of a function.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110831/cc7398a1/attachment.html>

More information about the es-discuss mailing list