<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>(Please include me explicitly on any follow-up discussion; I'm
not on the -experts list.)</p>
<p><br>
</p>
<p>1. Sealed types</p>
<p>The feature provides new modifiers for a type declaration, and a
list of permitted subtypes for sealed types.<br>
</p>
<p>For sealed types and permitted subtypes, javadoc will always
display the "sealed", "non-sealed" or "final" modifiers, even if
those modifiers are implicit in the source code [1].<br>
</p>
<p>For sealed types, javadoc will display the permitted subtypes
after the superclass and any superinterfaces. The names of all the
permitted subtypes are displayed, even if those types are not
generally accessible, so that a user who wishes to "switch" on the
different subtypes can determine if they have handled all
permitted subtypes. As with any reference to any type, the name
will be linked to the documentation for the type if it is
available, and just displayed as a name if the documentation is
not available.</p>
<p>Discussion: it remains to be seen how common it will be to permit
generally inaccessible subtypes, and whether it is desirable to
suppress the names of inaccessible permitted subtypes and replace
them with a phrase like "and more." Note the filter for
inaccessible permitted subtypes is a function of the javadoc
command line options `-public`, `-protected`, `-package` and
`-private`.</p>
<p>2. Records</p>
<p>The feature provides a new "kind" of type, containing a series of
named "state components" such that boilerplate methods can be
generated by the compiler if necessary.</p>
<p>As well as the new syntax, the `@param` tag in the documentation
comment for a record is extended to allow documentation to be
provided for each component. For example,<br>
</p>
<pre><tt> /**
* This is a record type.
* @param x This is the documentation for the 'x' component</tt><tt><tt>
* @param y This is the documentation for the 'y' component</tt>
*/
record R(int x, int y) { }
</tt></pre>
<p>For record types, javadoc will prominently display the state
components in a manner similar to any type arguments for a type.
In addition, for the canonical constructor, equals and hashCode
methods and any accessor methods, javadoc will provide default
documentation if none is provided in the source code. These
defaults will refer back to the documentation for the individual
components as appropriate.</p>
<p><br>
</p>
[1]
<a class="moz-txt-link-freetext"
href="https://mail.openjdk.java.net/pipermail/amber-spec-experts/2019-September/001593.html">https://mail.openjdk.java.net/pipermail/amber-spec-experts/2019-September/001593.html</a>
</body>
</html>