<html><body><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><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><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" <jonathan.gibbons@oracle.com><br><b>À: </b>"amber-spec-experts" <amber-spec-experts@openjdk.java.net><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">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">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">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">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></body></html>