__doc__ for functions, classes, objects etc.

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


On 30.08.2011 19:54, Rick Waldron 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:
>>
>>         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?
>
>
> I support this idea :)
>
> BTW, here are some incomplete numbers on "help()" (sort of)
> http://www.google.com/codesearch#search/&q=lang:%5Ejavascript$%20help%5C(&type=cs 
> <http://www.google.com/codesearch#search/&q=lang:%5Ejavascript$%20help%5C%28&type=cs>

OK, OK, you've convinced me ;) it's used much as I see. Though, would be 
the best name. Function.getDocumentation(...) is also nice but long. 
Funciton.getInfo(...) may return an object with meta-info: 
{documentation: "...", length: 2, arguments: {"a": int, "b": string}}. 
But don't wanna go down into the bikeshed.

Dmitry.

>
>     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/20110831/3b940ed2/attachment-0001.html>


More information about the es-discuss mailing list