__doc__ for functions, classes, objects etc.

Dmitry A. Soshnikov dmitry.soshnikov at gmail.com
Tue Aug 30 07:41:31 PDT 2011


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

So, what should I do to apply the first meaning?

Dmitry.

>
>     When the `help` function is called on the F object, the following
>     steps are taken:
>
>     1. If [[Class]] of the function is not "Function" throw TypeError
>     2. Let doc be [[Documentation]] property of F
>        2.1 If doc is `undefined` return empty string
>        2.2. return String(doc)
>
>     It's a simplified version of course (moreover, Allen wanted to
>     eliminate [[Class]], so -- it's just an example).
>
>     Do we need this?
>
>     Dmitry.
>
>
>     On 09.08.2011 23:59, Dmitry A. Soshnikov wrote:
>
>         On 23.08.2011 20:54, Brendan Eich wrote:
>
>             A convenient notation for multiline documentation
>             comments, with convenient reflection (*not* via toString()
>             scraping!), would be a fine thing.
>
>
>         Yes, exactly this -- help(...) function, and also good
>         auto-complete of object methods helped me some time ago
>         formerly to learn Python very quickly just playing with it in
>         console. By the way, ECMAScript (who will take responsibility
>         to implement the ECMAScript -- ethanol implementation? :))
>         also needs some installation binaries with the console. And
>         yes -- with this great features for learning -- auto-complete
>         of methods (the best thing to investigate objects just
>         pressing `tab`) and help(...) function. I remember ES4 had/has
>         the REPL, why not ES5? Of course we have all those consoles
>         directly from the browsers (and also Node.js REPL), but it
>         could be useful. Anyway, it's another topic, just relatively
>         touches help(...) functions.
>
>             Some of the design dimensions:
>
>             0. Comment vs. string / quasiliteral?
>
>             1. function-only, or object literal too -- or any declaration?
>
>
>         I think functions are the main case, yes. Not sure about
>         literals, since there are open issues such as, "how to
>         document a property" (via descriptor field?)?
>
>             2. Before function, a la javadoc comments, or first thing
>             in body, a la the prologue directive idea?
>
>
>         That's said, if "before", then we should consider white-spaces
>         and newlines after the comment and before the function header
>         (though, as well as in the prologue). If "before", then tones
>         of old code written in javadoc will just work with the new
>         engine. OTOH, this means that the exact syntax of javadocs
>         will be standardized at the level of the spec (and it's a
>         sound thing -- people will have to write exactly e.g.
>         @property that the "doc-er" catch it correctly. OTOH again --
>         why not? -- to standardize common syntax of documenting
>         functions). However, the spec may not parse the exact content
>         of the comment but just save it as a string, regardless of
>         what is written insides.
>
>         A variant with "inside" is also good, underlines that the
>         comment is sort of a function's "property" (I like yours
>         simple "doc" name for that). Both variants are good, just
>         "outside" has the advantage that the old code will just hook
>         on it.
>
>             3. Reflected via function .doc property, a
>             Function.extractDocComment static method, or something
>             even more mirror-like/stratified?
>
>
>         Yes, both are fine, ".doc" is great. Perhaps, even global
>         binding help(...).
>
>             I'm not sure what is best, I lack experience programming
>             in languages with doc-comment or triple-quoted equivalents
>             (Python attached tests, e.g.). Comments (heh) welcome.
>
>             Thinking about 1, I would start with function-only.
>
>
>         Yes, this is the main case.
>
>             For 2 I'm inclined to say "in body" because it's too easy
>             to lose the "before" context during the life of a
>             function, compared to losing part of the body by accident.
>
>
>         At first glance there should be no issues with parsing in both
>         cases. We sure have to restrict that only the first multiline
>         comment from _above_ of a function is treated as doc-comment.
>         It will not touch any other upper-comments
>
>         // this one isn't caught
>
>         /*
>         and this one also
>         */
>
>         /**
>          * but this is OK
>          */
>         function foo() {}
>
>         console.log(foo.doc); // "but this is OK"
>
>         With the prologue -- there also directives' places should be
>         considered. I think the best place for them is under the
>         doc-comment.
>
>         function foo() {
>
>          "" My function """
>
>          "use strict";
>         }
>
>             Regarding 3, I bet Function.extractDocComment or a better
>             name wins, especially if the whole solution allows
>             monkey-patching a polyfill for downrev browsers that
>             support source recovery (not SpiderMonkey's decompiler).
>
>
>         Yes, maybe.
>
>         Dmitry.
>
>
>     _______________________________________________
>     es-discuss mailing list
>     es-discuss at mozilla.org <mailto:es-discuss at mozilla.org>
>     https://mail.mozilla.org/listinfo/es-discuss
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110830/4ec0e4a0/attachment-0001.html>


More information about the es-discuss mailing list