On 10/11/19 12:49 PM, Remi Forax wrote:
Hi Johnathan,
as others said, i find the javadoc very clear.
Minor nits, for equals:
"Indicates whether some other object is "equal to" this one. The
objects are equal if the other object is of the same class and if all
the record components are equal. All components are compared with '=='."
Nope, they are compared using equals for reference and == for
primitives and the call order of the equals is not defined (for those
that write equals with side effects in it)
Rémi,
javadoc checks for the presence of primitives and references, and adapts
the text accordingly, In the case you are looking at, there are no
references, and so the text is correct. It seems wrong to talk about
using Objects.equals for references when there are none.
That being said, I guess I could qualify the text by somehow including
"This implemenatation..."
Note the more general text, talking about '==' and Objects.equals is
included in the general description in Record.equals.
And for hashCode and toString:
A line saying that the returned value may change from one execution
of the VM to an other is missing.
I'm presuming that is only true for hashCode, and not toString.
-- Jon
cheers,
Rémi
------------------------------------------------------------------------
*De: *"jonathan gibbons" <[email protected]>
*À: *"amber-spec-experts" <[email protected]>
*Envoyé: *Vendredi 11 Octobre 2019 02:00:20
*Objet: *sample javadoc output for records and sealed types.
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
