<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class="">I think it would be good if the javadoc always said “final” for records, regardless of what was in the source.  <br class=""><div><br class=""><blockquote type="cite" class=""><div class="">On Oct 11, 2019, at 11:37 AM, Chris Hegarty <<a href="mailto:chris.hegarty@oracle.com" class="">chris.hegarty@oracle.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="Content-Type" content="text/html; charset=utf-8" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class="">Jon,<div class=""><br class=""></div><div class="">The javadoc looks great.</div><div class=""><br class=""></div><div class="">I’m sure that this has come up already, but I cannot find it, so I’ll ask here.</div><div class=""><br class=""></div><div class="">Should the javadoc include the fact that a record class is `final`? Or is that implied by the fact that it is a record?</div><div class=""><br class=""></div><div class="">The reason I ask is that one can write `public final record R {}`. Will the javadoc for `R` show final?  If so, then it could be a little confusing that the docs for some records may show final and others not. Maybe it just needs to be consistent one way or another.  ( I found myself drawn to this question by the obvious presence of the public constructor )</div><div class=""> </div><div class="">-Chris.<br class=""><div class=""><br class=""><blockquote type="cite" class=""><div class="">On 11 Oct 2019, at 01:00, Jonathan Gibbons <<a href="mailto:jonathan.gibbons@oracle.com" class="">jonathan.gibbons@oracle.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class="">
  

    <meta http-equiv="content-type" content="text/html; charset=utf-8" class="">
  
  <div text="#000000" bgcolor="#FFFFFF" class=""><p class="">I've posted the javadoc output from some small examples of
      records and sealed types.</p><p class="">Three of the examples, Point, BinaryNode and Holder, were
      suggested by Brian as<br class="">
      commonly used examples. The last example, Coords, declares a
      sealed type with<br class="">
      two different records as subtypes, just to show how the features
      can be used together.</p><p class="">You can find the output here:<br class="">
    </p>
    <ol class="">
      <li class=""><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 class="">
        <br class="">
        This is output from a "simple" run of javadoc, that does not
        link to JDK documentation.<br class="">
        In this version, references into java.base etc show up as
        unlinked monospaced text.<br class="">
        <br class="">
      </li>
      <li class=""><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 class="">
        <br class="">
        This is the output from a similar run of javadoc (same
        examples), but this time the<br class="">
        -linkoffline option was used so that references into java.base
        are linked as you would expect.</li>
    </ol><p class=""><br class="">
    </p><p class="">In both cases, I also used the "-linksource" option, so that you
      can also see the original<br class="">
      source file. Look for the link in the declaration of the type name
      near the top of each page. <br class="">
      For example, click on "Foo" where you see "public record Foo",
      etc.</p><p class="">You can also see the raw source files here:<br class="">
<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 class="">------</p><p class="">Discussion:</p><p class="">Currently, the generated documentation consistently uses the full
      phrase "record components"<br class="">
      when referencing record components. This means that some of the
      generated text feels a <br class="">
      little clunky. I see that in some of the hard-written doc comments
      (e.g. on java.lang.Record)<br class="">
      the phrase is shortened to just "component" when the context is
      obvious.  Do we want to do<br class="">
      the same here? Are there any guidelines on the terminology?</p><p class="">Currently, following established historical precedent, records
      appear in their own group<br class="">
      on the package page, alongside individual groups for classes,
      interfaces, enums, exceptions, <br class="">
      errors and annotation types.  For example, look at the docs for
      any recent version of java.lang:<br class="">
<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 class="">
      It may be that 7 (!!) groups is a few too many, and that maybe we
      should reorganize these pages<br class="">
      a bit, perhaps moving towards a tabbed table, of the sort we use
      on other pages. But whether<br class="">
      or not we do anything is out of scope for this project, and should
      be handled separately, as a <br class="">
      distinct enhancement for javadoc.<br class="">
    </p><p class="">-- Jon<br class="">
    </p>
    <br class="">
  </div>

</div></blockquote></div><br class=""></div></div></div></blockquote></div><br class=""></body></html>