sample javadoc output for records and sealed types.

Jonathan Gibbons jonathan.gibbons at
Fri Oct 11 19:32:02 UTC 2019

I've added two new examples, for a serializable record 
(SerializablePoint) and a serializable type with a record for a 
serialization proxy (SerializableProxy): the name for that one is 
intended to be description of the example, although admittedly, it is 
not a particularly good name for the functionality of the class!

The sample output has been updated in place.

-- Jon

On 10/10/19 5:00 PM, Jonathan Gibbons wrote:
> I've posted the javadoc output from some small examples of records and 
> sealed types.
> Three of the examples, Point, BinaryNode and Holder, were suggested by 
> Brian as
> commonly used examples. The last example, Coords, declares a sealed 
> type with
> two different records as subtypes, just to show how the features can 
> be used together.
> You can find the output here:
> 1. 
>    This is output from a "simple" run of javadoc, that does not link to
>    JDK documentation.
>    In this version, references into java.base etc show up as unlinked
>    monospaced text.
> 2. 
>    This is the output from a similar run of javadoc (same examples),
>    but this time the
>    -linkoffline option was used so that references into java.base are
>    linked as you would expect.
> In both cases, I also used the "-linksource" option, so that you can 
> also see the original
> source file. Look for the link in the declaration of the type name 
> near the top of each page.
> For example, click on "Foo" where you see "public record Foo", etc.
> You can also see the raw source files here:
> ------
> Discussion:
> Currently, the generated documentation consistently uses the full 
> phrase "record components"
> when referencing record components. This means that some of the 
> generated text feels a
> little clunky. I see that in some of the hard-written doc comments 
> (e.g. on java.lang.Record)
> the phrase is shortened to just "component" when the context is 
> obvious.  Do we want to do
> the same here? Are there any guidelines on the terminology?
> Currently, following established historical precedent, records appear 
> in their own group
> on the package page, alongside individual groups for classes, 
> interfaces, enums, exceptions,
> errors and annotation types.  For example, look at the docs for any 
> recent version of java.lang:
> It may be that 7 (!!) groups is a few too many, and that maybe we 
> should reorganize these pages
> a bit, perhaps moving towards a tabbed table, of the sort we use on 
> other pages. But whether
> or not we do anything is out of scope for this project, and should be 
> handled separately, as a
> distinct enhancement for javadoc.
> -- Jon

More information about the amber-spec-experts mailing list