__doc__ for functions, classes, objects etc.

Dean Landolt dean at deanlandolt.com
Tue Aug 30 08:33:48 PDT 2011

On Tue, Aug 30, 2011 at 10:41 AM, Dmitry A. Soshnikov <
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> 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.

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.

> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110830/8b5d3e80/attachment.html>

More information about the es-discuss mailing list