Noted. But I also note we suppress always-on modifiers for other
elements :-) So I guess we choose on a case-by-case basis.
FWIW, javadoc is driven by the Language Model (javax.lang.model) API,
and not what is in the source code.
-- Jon
On 10/11/19 8:43 AM, Brian Goetz wrote:
I think it would be good if the javadoc always said “final” for
records, regardless of what was in the source.
On Oct 11, 2019, at 11:37 AM, Chris Hegarty <[email protected]
<mailto:[email protected]>> wrote:
Jon,
The javadoc looks great.
I’m sure that this has come up already, but I cannot find it, so I’ll
ask here.
Should the javadoc include the fact that a record class is `final`?
Or is that implied by the fact that it is a record?
The reason I ask is that one can write `public final record R {}`.
Will the javadoc for `R` show final? If so, then it could be a
little confusing that the docs for some records may show final and
others not. Maybe it just needs to be consistent one way or another.
( I found myself drawn to this question by the obvious presence of
the public constructor )
-Chris.
On 11 Oct 2019, at 01:00, Jonathan Gibbons
<[email protected] <mailto:[email protected]>>
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
