__doc__ for functions, classes, objects etc.

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


Right. And this is where Python just wins. In respect of bult-ins and 
methods provided by framework authors. That's said in the initial 
letter, we can always go to the language documentation website and read 
it, but to the help "in-place" seems much better.

Though, there is another issue here (beside the source- and byte- code 
size increasing). The "offline" documentation embedded inside the 
function objects may become obsolete, while the online is up-to-date. 
But, for the specified built-ins it's not the case, since the spec 
doesn't change too often. And regarding user-defined framework codes, 
anyway the code is parsed each time -- it is the property and the deal 
of the JS engine to correctly parse doc-comment and assign it as a 
property to a function. That is, the documentation may change in-time 
and if you use external script file, then you always have up-to-date 
documentation.

Dmitry.


On 30.08.2011 20:09, Dave Fugate wrote:
>
> This feature is particularly useful for /framework/ authors and their 
> users.  Countless times I've found myself using a browser's console 
> debugging tool to figure out why something's busted.  In these cases, 
> I nearly always resort to navigating to some JS framework's website 
> for their documentation or scrutinizing their code directly to figure 
> out what's going wrong.  If I could just call 
> 'printHelp(xyz....someMethod)', less of my time would be used.  The 
> other bit of utility here is that framework documentation can live 
> side-by-side with the code and be automatically generated from it 
> (e.g., http://pydoc.org/2.5.1/timeit.html) as opposed to maintaining 
> it separately.  A very useful feature to have from my Python-biased 
> perspectiveJ
>
> My best,
>
> Dave
>
> *From:*es-discuss-bounces at mozilla.org 
> [mailto:es-discuss-bounces at mozilla.org] *On Behalf Of *Dmitry A. Soshnikov
> *Sent:* Tuesday, August 30, 2011 7:42 AM
> *To:* Rick Waldron
> *Cc:* Brendan Eich; es-discuss Steen
> *Subject:* Re: __doc__ for functions, classes, objects etc.
>
> 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/20110831/3a76af90/attachment-0001.html>


More information about the es-discuss mailing list