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