<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    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.<br>
    <br>
    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.<br>
    <br>
    Dmitry.<br>
    <br>
    <br>
    On 30.08.2011 20:09, Dave Fugate wrote:
    <blockquote
cite="mid:299545F35D442642800736DBA0C3AA28122122B1@TK5EX14MBXC262.redmond.corp.microsoft.com"
      type="cite">
      <meta http-equiv="Content-Type" content="text/html;
        charset=ISO-8859-1">
      <meta name="Generator" content="Microsoft Word 14 (filtered
        medium)">
      <style><!--
/* Font Definitions */
@font-face
        {font-family:Wingdings;
        panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
        {font-family:Wingdings;
        panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
        {font-family:Calibri;
        panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
        {font-family:Tahoma;
        panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
        {margin:0in;
        margin-bottom:.0001pt;
        font-size:12.0pt;
        font-family:"Times New Roman","serif";
        color:black;}
a:link, span.MsoHyperlink
        {mso-style-priority:99;
        color:blue;
        text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
        {mso-style-priority:99;
        color:purple;
        text-decoration:underline;}
span.EmailStyle17
        {mso-style-type:personal-reply;
        font-family:"Calibri","sans-serif";
        color:#1F497D;}
.MsoChpDefault
        {mso-style-type:export-only;
        font-size:10.0pt;}
@page WordSection1
        {size:8.5in 11.0in;
        margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
        {page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
      <div class="WordSection1">
        <p class="MsoNormal"><span
style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">This
            feature is particularly useful for
            <i>framework</i> 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., <a
              moz-do-not-send="true"
              href="http://pydoc.org/2.5.1/timeit.html">
              http://pydoc.org/2.5.1/timeit.html</a>) as opposed to
            maintaining it separately.  A very useful feature to have
            from my Python-biased perspective</span><span
            style="font-size:11.0pt;font-family:Wingdings;color:#1F497D">J</span><span
style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p></o:p></span></p>
        <p class="MsoNormal"><span
style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
        <p class="MsoNormal"><span
style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">My
            best,<o:p></o:p></span></p>
        <p class="MsoNormal"><span
style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
        <p class="MsoNormal"><span
style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Dave<o:p></o:p></span></p>
        <p class="MsoNormal"><span
style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
        <div>
          <div style="border:none;border-top:solid #B5C4DF
            1.0pt;padding:3.0pt 0in 0in 0in">
            <p class="MsoNormal"><b><span
style="font-size:10.0pt;font-family:"Tahoma","sans-serif";color:windowtext">From:</span></b><span
style="font-size:10.0pt;font-family:"Tahoma","sans-serif";color:windowtext">
                <a class="moz-txt-link-abbreviated" href="mailto:es-discuss-bounces@mozilla.org">es-discuss-bounces@mozilla.org</a>
                [<a class="moz-txt-link-freetext" href="mailto:es-discuss-bounces@mozilla.org">mailto:es-discuss-bounces@mozilla.org</a>]
                <b>On Behalf Of </b>Dmitry A. Soshnikov<br>
                <b>Sent:</b> Tuesday, August 30, 2011 7:42 AM<br>
                <b>To:</b> Rick Waldron<br>
                <b>Cc:</b> Brendan Eich; es-discuss Steen<br>
                <b>Subject:</b> Re: __doc__ for functions, classes,
                objects etc.<o:p></o:p></span></p>
          </div>
        </div>
        <p class="MsoNormal"><o:p> </o:p></p>
        <p class="MsoNormal">On 30.08.2011 17:41, Rick Waldron wrote: <o:p></o:p></p>
        <div>
          <div>
            <p class="MsoNormal">On Tue, Aug 30, 2011 at 3:39 AM, Dmitry
              A. Soshnikov <<a moz-do-not-send="true"
                href="mailto:dmitry.soshnikov@gmail.com">dmitry.soshnikov@gmail.com</a>>
              wrote:<o:p></o:p></p>
            <p class="MsoNormal">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)<o:p></o:p></p>
            <div>
              <p class="MsoNormal"><o:p> </o:p></p>
            </div>
            <div>
              <p class="MsoNormal">A built-in, global object function
                property named "help()" will no doubt conflict with
                userland code<o:p></o:p></p>
            </div>
            <div>
              <p class="MsoNormal"><o:p> </o:p></p>
            </div>
          </div>
        </div>
        <p class="MsoNormal"><br>
          <br>
          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>
          <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>
          <br>
          Dmitry.<br>
          <br>
          <br>
          <o:p></o:p></p>
        <div>
          <div>
            <div>
              <p class="MsoNormal"> <o:p></o:p></p>
            </div>
            <blockquote style="border:none;border-left:solid #CCCCCC
              1.0pt;padding:0in 0in 0in
              6.0pt;margin-left:4.8pt;margin-right:0in">
              <p class="MsoNormal"><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>
                <span style="color:#888888"><br>
                  Dmitry.</span> <o:p></o:p></p>
              <div>
                <div>
                  <p class="MsoNormal"><br>
                    <br>
                    On 09.08.2011 23:59, Dmitry A. Soshnikov wrote:<o:p></o:p></p>
                  <p class="MsoNormal">On 23.08.2011 20:54, Brendan Eich
                    wrote:<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt">A
                    convenient notation for multiline documentation
                    comments, with convenient reflection (*not* via
                    toString() scraping!), would be a fine thing.<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt"><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.<o:p></o:p></p>
                  <p class="MsoNormal">Some of the design dimensions:<br>
                    <br>
                    0. Comment vs. string / quasiliteral?<br>
                    <br>
                    1. function-only, or object literal too -- or any
                    declaration?<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt"><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?)?<o:p></o:p></p>
                  <p class="MsoNormal">2. Before function, a la javadoc
                    comments, or first thing in body, a la the prologue
                    directive idea?<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt"><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.<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt">3.
                    Reflected via function .doc property, a
                    Function.extractDocComment static method, or
                    something even more mirror-like/stratified?<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt"><br>
                    Yes, both are fine, ".doc" is great. Perhaps, even
                    global binding help(...).<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt">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.<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt"><br>
                    Yes, this is the main case.<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt">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.<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt"><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>
                    }<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt">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).<o:p></o:p></p>
                  <p class="MsoNormal" style="margin-bottom:12.0pt"><br>
                    Yes, maybe.<br>
                    <br>
                    Dmitry.<o:p></o:p></p>
                  <p class="MsoNormal"><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><o:p></o:p></p>
                </div>
              </div>
            </blockquote>
          </div>
          <p class="MsoNormal"><o:p> </o:p></p>
        </div>
        <p class="MsoNormal"><o:p> </o:p></p>
      </div>
    </blockquote>
    <br>
  </body>
</html>