__doc__ for functions, classes, objects etc.

Rick Waldron waldron.rick at gmail.com
Tue Aug 30 08:54:23 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:
>>
>> 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


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


More information about the es-discuss mailing list