sample javadoc output for records and sealed types.

[Jonathan Gibbons]

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. http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-no-link/


    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. http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-with-link/

    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:
http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/src/

------

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:
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/package-summary.html
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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/amber-spec-experts/attachments/20191010/3d3f56ad/attachment-0001.html>