On Tue, Aug 30, 2011 at 10:41 AM, Dmitry A. Soshnikov < [email protected]> wrote:
> On 30.08.2011 17:41, Rick Waldron wrote: > > On Tue, Aug 30, 2011 at 3:39 AM, Dmitry A. Soshnikov < > [email protected]> 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 >> [email protected] >> https://mail.mozilla.org/listinfo/es-discuss >> > > >
_______________________________________________ es-discuss mailing list [email protected] https://mail.mozilla.org/listinfo/es-discuss
