sample javadoc output for records and sealed types.

[Éamonn McManus]

I notice that the meaningful description Returns the Cartesian x-coordinate
<http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-with-link/examples/Coords.html#x()>
from
the Coords interface has been overridden by the less helpful generated
description Returns the value of the x record component
<http://cr.openjdk.java.net/~jjg/amber-records-and-sealed-types/api-with-link/examples/Coords.Cartesian.html#x()>
in
Coords.Cartesian. Is there a way to prevent that from happening, at least
when parent and child are part of the same javadoc run?

On Thu, 10 Oct 2019 at 17:04, Jonathan Gibbons <jonathan.gibbons at oracle.com>
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.
> 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
>
>
>