<html>
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    <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/">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/">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/">http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/src/</a></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">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>
  </body>
</html>