(Please include me explicitly on any follow-up discussion; I'm not on
the -experts list.)
1. Sealed types
The feature provides new modifiers for a type declaration, and a list of
permitted subtypes for sealed types.
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].
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.
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`.
2. Records
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.
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,
/** * This is a record type. * @param x This is the documentation
for the 'x' component* @param y This is the documentation for the 'y'
component */ record R(int x, int y) { }
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.
[1]
https://mail.openjdk.java.net/pipermail/amber-spec-experts/2019-September/001593.html
