<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>