sample javadoc output for records and sealed types.

[Jonathan Gibbons]

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" <jonathan.gibbons at oracle.com>
>     *À: *"amber-spec-experts" <amber-spec-experts at 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/
>
>
>         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
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/amber-spec-experts/attachments/20191013/d1d1ccf1/attachment.html>