sample javadoc output for records and sealed types.

[Jonathan Gibbons]

Yeah, I'd noticed that too.

It's not clear to me that you always want the inherited description in 
preference to the generated description, although I agree that in this 
case it would be clearer.

Note that you can always force the use of the inherited description with 
/** {@inheritDoc} */.

-- Jon

On 10/12/19 10:21 AM, Éamonn McManus wrote:
> 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 <mailto: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
>
>