<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    On 30.08.2011 19:54, Rick Waldron wrote:
    <blockquote
cite="mid:CAHfnhfqNbAT7mkuXd_CuJym_Cd43uBTMAYaS2bosSAMYPK_q2A@mail.gmail.com"
      type="cite"><br>
      <br>
      <div class="gmail_quote">On Tue, Aug 30, 2011 at 10:41 AM, Dmitry
        A. Soshnikov <span dir="ltr"><<a moz-do-not-send="true"
            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
                        moz-do-not-send="true"
                        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 moz-do-not-send="true"
href="http://www.google.com/codesearch#search/&q=lang:%5Ejavascript$%20help%5C%28&type=cs">http://www.google.com/codesearch#search/&q=lang:%5Ejavascript$%20help%5C(&type=cs</a></div>
      </div>
    </blockquote>
    <br>
    OK, OK, you've convinced me ;) it's used much as I see. Though,
    would be the best name. Function.getDocumentation(...) is also nice
    but long. Funciton.getInfo(...) may return an object with meta-info:
    {documentation: "...", length: 2, arguments: {"a": int, "b":
    string}}. But don't wanna go down into the bikeshed.<br>
    <br>
    Dmitry.<br>
    <br>
    <blockquote
cite="mid:CAHfnhfqNbAT7mkuXd_CuJym_Cd43uBTMAYaS2bosSAMYPK_q2A@mail.gmail.com"
      type="cite">
      <div class="gmail_quote">
        <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 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 moz-do-not-send="true"
                              href="mailto:es-discuss@mozilla.org"
                              target="_blank">es-discuss@mozilla.org</a><br>
                            <a moz-do-not-send="true"
                              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>
    </blockquote>
    <br>
  </body>
</html>