<br><br><div class="gmail_quote">On Tue, Aug 30, 2011 at 10:41 AM, Dmitry A. Soshnikov <span dir="ltr"><<a href="mailto:dmitry.soshnikov@gmail.com">dmitry.soshnikov@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">


  
    
  
  <div bgcolor="#FFFFFF" text="#000000"><div class="im">
    On 30.08.2011 17:41, Rick Waldron wrote:
    <blockquote type="cite">
      <div>
        <div class="gmail_quote">On Tue, Aug 30, 2011 at 3:39 AM, Dmitry
          A. Soshnikov <span dir="ltr"><<a href="mailto:dmitry.soshnikov@gmail.com" target="_blank">dmitry.soshnikov@gmail.com</a>></span>
          wrote:<br>
          <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
            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.<br>
            <br>
            Some summarized features below:<br>
            <br>
            + 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)<br>
            + Auto-suggest and hints of parameters and their types when
            typing function name in console.<br>
            + 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).<br>
            - 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")<br>
            <br>
            As an example I show a spec description for `parseInt`
            function:<br>
            <br>
            15.1.2.2 parseInt (string , radix)<br>
            <br>
            Let [[Documentation]] property of the `parseInt` function be
            the following string:<br>
            <br>
            "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."<br>
            <br>
            ...<br>
            <br>
            x.x.xx help(F)<br>
          </blockquote>
          <div><br>
          </div>
          <div>A built-in, global object function property named
            "help()" will no doubt conflict with userland code</div>
          <div><br>
          </div>
        </div>
      </div>
    </blockquote>
    <br>
    <br></div>
    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?<br></div></blockquote><div><br></div><div>I support this idea :)</div><div><br></div><div>BTW, here are some incomplete numbers on "help()" (sort of)</div>

<div><a href="http://www.google.com/codesearch#search/&q=lang:%5Ejavascript$%20help%5C(&type=cs">http://www.google.com/codesearch#search/&q=lang:%5Ejavascript$%20help%5C(&type=cs</a></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">

<div bgcolor="#FFFFFF" text="#000000">
    <br>
    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.<br>
    <br>
    So, what should I do to apply the first meaning?<br><font color="#888888">
    <br>
    Dmitry.</font><div><div></div><div class="h5"><br>
    <br>
    <blockquote type="cite">
      <div>
        <div class="gmail_quote">
          <div> </div>
          <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
            <br>
            When the `help` function is called on the F object, the
            following steps are taken:<br>
            <br>
            1. If [[Class]] of the function is not "Function" throw
            TypeError<br>
            2. Let doc be [[Documentation]] property of F<br>
               2.1 If doc is `undefined` return empty string<br>
               2.2. return String(doc)<br>
            <br>
            It's a simplified version of course (moreover, Allen wanted
            to eliminate [[Class]], so -- it's just an example).<br>
            <br>
            Do we need this?<br>
            <font color="#888888">
              <br>
              Dmitry.</font>
            <div>
              <div><br>
                <br>
                On 09.08.2011 23:59, Dmitry A. Soshnikov wrote:<br>
                <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                  On 23.08.2011 20:54, Brendan Eich wrote:<br>
                  <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                    A convenient notation for multiline documentation
                    comments, with convenient reflection (*not* via
                    toString() scraping!), would be a fine thing.<br>
                    <br>
                  </blockquote>
                  <br>
                  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.<br>
                  <br>
                  <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                    Some of the design dimensions:<br>
                    <br>
                    0. Comment vs. string / quasiliteral?<br>
                    <br>
                    1. function-only, or object literal too -- or any
                    declaration?<br>
                  </blockquote>
                  <br>
                  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?)?<br>
                  <br>
                  <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                    2. Before function, a la javadoc comments, or first
                    thing in body, a la the prologue directive idea?<br>
                  </blockquote>
                  <br>
                  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.<br>
                  <br>
                  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.<br>
                  <br>
                  <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                    3. Reflected via function .doc property, a
                    Function.extractDocComment static method, or
                    something even more mirror-like/stratified?<br>
                    <br>
                  </blockquote>
                  <br>
                  Yes, both are fine, ".doc" is great. Perhaps, even
                  global binding help(...).<br>
                  <br>
                  <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                    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.<br>
                    <br>
                    Thinking about 1, I would start with function-only.<br>
                    <br>
                  </blockquote>
                  <br>
                  Yes, this is the main case.<br>
                  <br>
                  <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                    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.<br>
                    <br>
                  </blockquote>
                  <br>
                  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<br>
                  <br>
                  // this one isn't caught<br>
                  <br>
                  /*<br>
                  and this one also<br>
                  */<br>
                  <br>
                  /**<br>
                   * but this is OK<br>
                   */<br>
                  function foo() {}<br>
                  <br>
                  console.log(foo.doc); // "but this is OK"<br>
                  <br>
                  With the prologue -- there also directives' places
                  should be considered. I think the best place for them
                  is under the doc-comment.<br>
                  <br>
                  function foo() {<br>
                  <br>
                   "" My function """<br>
                  <br>
                   "use strict";<br>
                  }<br>
                  <br>
                  <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
                    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).<br>
                    <br>
                  </blockquote>
                  <br>
                  Yes, maybe.<br>
                  <br>
                  Dmitry.<br>
                  <br>
                </blockquote>
                <br>
                _______________________________________________<br>
                es-discuss mailing list<br>
                <a href="mailto:es-discuss@mozilla.org" target="_blank">es-discuss@mozilla.org</a><br>
                <a href="https://mail.mozilla.org/listinfo/es-discuss" target="_blank">https://mail.mozilla.org/listinfo/es-discuss</a><br>
              </div>
            </div>
          </blockquote>
        </div>
        <br>
      </div>
    </blockquote>
    <br>
  </div></div></div>

</blockquote></div><br>