<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <p><br>
    </p>
    <div class="moz-cite-prefix">On 10/11/19 12:49 PM, Remi Forax wrote:<br>
    </div>
    <blockquote type="cite"
      cite="mid:1273398846.2502101.1570823384368.JavaMail.zimbra@u-pem.fr">
      <meta http-equiv="content-type" content="text/html; charset=UTF-8">
      <div style="font-family: arial, helvetica, sans-serif; font-size:
        12pt; color: #000000">
        <div>Hi Johnathan,<br data-mce-bogus="1">
        </div>
        <div>as others said, i find the javadoc very clear.<br
            data-mce-bogus="1">
        </div>
        <div><br data-mce-bogus="1">
        </div>
        <div>Minor nits, for equals:<br>
        </div>
        <div>  "Indicates whether some other object is "equal to" this
          one. The objects are equal if the other object is of the same
          class and if all the record components are equal. All
          components are compared with '=='."<br data-mce-bogus="1">
        </div>
        <div>Nope, they are compared using equals for reference and ==
          for primitives and the call order of the equals is not defined
          (for those that write equals with side effects in it)<br
            data-mce-bogus="1">
        </div>
      </div>
    </blockquote>
    <p>Rémi,</p>
    <p>javadoc checks for the presence of primitives and references, and
      adapts the text accordingly,  In the case you are looking at,
      there are no references, and so the text is correct. It seems
      wrong to talk about using Objects.equals for references when there
      are none.</p>
    <p>That being said, I guess I could qualify the text by somehow
      including "This implemenatation..."</p>
    <p>Note the more general text, talking about '==' and Objects.equals
      is included in the general description in Record.equals.</p>
    <p><br>
    </p>
    <blockquote type="cite"
      cite="mid:1273398846.2502101.1570823384368.JavaMail.zimbra@u-pem.fr">
      <div style="font-family: arial, helvetica, sans-serif; font-size:
        12pt; color: #000000">
        <div><br data-mce-bogus="1">
        </div>
        <div>And for hashCode and toString:<br data-mce-bogus="1">
        </div>
        <div>  A line saying that the returned value may change from one
          execution of the VM to an other is missing.</div>
      </div>
    </blockquote>
    <p>I'm presuming that is only true for hashCode, and not toString.<br>
    </p>
    <p>-- Jon<br>
    </p>
    <blockquote type="cite"
      cite="mid:1273398846.2502101.1570823384368.JavaMail.zimbra@u-pem.fr">
      <div style="font-family: arial, helvetica, sans-serif; font-size:
        12pt; color: #000000">
        <div><br data-mce-bogus="1">
        </div>
        <div>cheers,<br data-mce-bogus="1">
        </div>
        <div>Rémi</div>
        <div><br>
        </div>
        <hr id="zwchr" data-marker="__DIVIDER__">
        <div data-marker="__HEADERS__">
          <blockquote style="border-left:2px solid
#1010FF;margin-left:5px;padding-left:5px;color:#000;font-weight:normal;font-style:normal;text-decoration:none;font-family:Helvetica,Arial,sans-serif;font-size:12pt;"><b>De:
            </b>"jonathan gibbons" <a class="moz-txt-link-rfc2396E" href="mailto:jonathan.gibbons@oracle.com"><jonathan.gibbons@oracle.com></a><br>
            <b>À: </b>"amber-spec-experts"
            <a class="moz-txt-link-rfc2396E" href="mailto:amber-spec-experts@openjdk.java.net"><amber-spec-experts@openjdk.java.net></a><br>
            <b>Envoyé: </b>Vendredi 11 Octobre 2019 02:00:20<br>
            <b>Objet: </b>sample javadoc output for records and sealed
            types.<br>
          </blockquote>
        </div>
        <div data-marker="__QUOTED_TEXT__">
          <blockquote style="border-left:2px solid
#1010FF;margin-left:5px;padding-left:5px;color:#000;font-weight:normal;font-style:normal;text-decoration:none;font-family:Helvetica,Arial,sans-serif;font-size:12pt;">
            <p>I've posted the javadoc output from some small examples
              of records and sealed types.</p>
            <p>Three of the examples, Point, BinaryNode and Holder, were
              suggested by Brian as<br>
              commonly used examples. The last example, Coords, declares
              a sealed type with<br>
              two different records as subtypes, just to show how the
              features can be used together.</p>
            <p>You can find the output here:<br>
            </p>
            <ol>
              <li><a class="moz-txt-link-freetext"
href="http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-no-link/"
                  target="_blank" moz-do-not-send="true">http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-no-link/</a>
                <br>
                <br>
                This is output from a "simple" run of javadoc, that does
                not link to JDK documentation.<br>
                In this version, references into java.base etc show up
                as unlinked monospaced text.<br>
                <br>
              </li>
              <li><a class="moz-txt-link-freetext"
href="http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-with-link/"
                  target="_blank" moz-do-not-send="true">http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-with-link/</a><br>
                <br>
                This is the output from a similar run of javadoc (same
                examples), but this time the<br>
                -linkoffline option was used so that references into
                java.base are linked as you would expect.</li>
            </ol>
            <p><br>
            </p>
            <p>In both cases, I also used the "-linksource" option, so
              that you can also see the original<br>
              source file. Look for the link in the declaration of the
              type name near the top of each page. <br>
              For example, click on "Foo" where you see "public record
              Foo", etc.</p>
            <p>You can also see the raw source files here:<br>
              <a class="moz-txt-link-freetext"
href="http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/src/"
                target="_blank" moz-do-not-send="true">http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/src/</a><br
                data-mce-bogus="1">
            </p>
            <p>------</p>
            <p>Discussion:</p>
            <p>Currently, the generated documentation consistently uses
              the full phrase "record components"<br>
              when referencing record components. This means that some
              of the generated text feels a <br>
              little clunky. I see that in some of the hard-written doc
              comments (e.g. on java.lang.Record)<br>
              the phrase is shortened to just "component" when the
              context is obvious.  Do we want to do<br>
              the same here? Are there any guidelines on the
              terminology?</p>
            <p>Currently, following established historical precedent,
              records appear in their own group<br>
              on the package page, alongside individual groups for
              classes, interfaces, enums, exceptions, <br>
              errors and annotation types.  For example, look at the
              docs for any recent version of java.lang:<br>
              <a class="moz-txt-link-freetext"
href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/package-summary.html"
                target="_blank" moz-do-not-send="true">https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/package-summary.html</a><br>
              It may be that 7 (!!) groups is a few too many, and that
              maybe we should reorganize these pages<br>
              a bit, perhaps moving towards a tabbed table, of the sort
              we use on other pages. But whether<br>
              or not we do anything is out of scope for this project,
              and should be handled separately, as a <br>
              distinct enhancement for javadoc.<br>
            </p>
            <p>-- Jon<br>
            </p>
            <br>
            <br>
          </blockquote>
        </div>
      </div>
    </blockquote>
  </body>
</html>