javadoc support for records and sealed types

[Jonathan Gibbons]

(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 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/amber-spec-experts/attachments/20190926/52f353e8/attachment.html>