__doc__ for functions, classes, objects etc.

Rick Waldron waldron.rick at gmail.com
Tue Aug 30 06:41:10 PDT 2011


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



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


More information about the es-discuss mailing list