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)
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. cheers, Rémi > De: "jonathan gibbons" <jonathan.gibb...@oracle.com> > À: "amber-spec-experts" <amber-spec-experts@openjdk.java.net> > 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/ > | > 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/ > | > > 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/ | > 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 > | > 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
