<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>I think the output looks very clean. On the 'sealed' part I have
no objectctions.</p>
<p>On records, what you did looks, again, very clean. The only
comment I have there is that it "feels" like something is missing
in the summary section... e.g. for some reason I would expect a
"record components summary" there. I noted that you lifted the
components to the toplevel doc, but I wondering if that's the
right move.</p>
<p>If we had specific entries for components, then we could also
link e.g. the accessor to the component summary which would be, I
think, cool. In other words, the treatment of JavaFX comes to
mind:</p>
<p><a class="moz-txt-link-freetext" href="https://docs.oracle.com/javase/9/docs/api/javafx/scene/chart/Chart.html">https://docs.oracle.com/javase/9/docs/api/javafx/scene/chart/Chart.html</a></p>
<p>Also, there's a precedent: enums:</p>
<p><a class="moz-txt-link-freetext" href="https://docs.oracle.com/javase/9/docs/api/java/lang/annotation/ElementType.html">https://docs.oracle.com/javase/9/docs/api/java/lang/annotation/ElementType.html</a></p>
<p>Here, again, we have a summary section for all the constants.</p>
<p>Don't get me wrong, what you have is good enough for day 1, I'm
mostly trying to see how much rope we can pull.</p>
<p>Maurizio<br>
</p>
<p><br>
</p>
<div class="moz-cite-prefix">On 11/10/2019 01:00, Jonathan Gibbons
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:a91701d7-f799-afa7-afe5-0ef196b33363@oracle.com">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<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/"
moz-do-not-send="true">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/"
moz-do-not-send="true">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/"
moz-do-not-send="true">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"
moz-do-not-send="true">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>
</blockquote>
</body>
</html>