RFR: JEP 359-Records: javadoc code

[Remi Forax]

----- Mail original -----
> De: "Brian Goetz" <brian.goetz at oracle.com>
> À: "jonathan gibbons" <jonathan.gibbons at oracle.com>
> Cc: "amber-dev" <amber-dev at openjdk.java.net>, "javadoc-dev" <javadoc-dev at openjdk.java.net>, "compiler-dev"
> <compiler-dev at openjdk.java.net>, "Chris Hegarty" <chris.hegarty at oracle.com>
> Envoyé: Jeudi 31 Octobre 2019 15:05:33
> Objet: Re: RFR: JEP 359-Records: javadoc code

> Let’s look at this through the lens of “what information would the reader want
> to know about this class.”  And surely, finality is one of the bits of
> information the reader wants to know, because they might be wondering “can I
> subclass this.”  On the other hand, you might say “well of course, readers know
> that records are final, because the language says they are.”  And the treatment
> of enums (and public interface methods) in Javadoc is consistent with this
> counter-theory.
> 
> So I think its OK to go either way on finality, and consistency probably pushes
> us towards doing the same thing we do with enums.
> 
> For nested classes, on the other hand, I’m not quite as sure.  The rule about
> “nested records are implicitly static” is a little more subtle than the one
> about finality.

I will just add that enums have exactly the same rule, an enum is always static when nested in another class,
so whatever we decide, it should be the same for enums.

Rémi

> 
>> On Oct 31, 2019, at 9:59 AM, Jonathan Gibbons <jonathan.gibbons at oracle.com>
>> wrote:
>> 
>> 
>> On 10/31/19 3:31 AM, Chris Hegarty wrote:
>>> Jon,
>>> 
>>>> On 30 Oct 2019, at 23:50, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>>> 
>>>> ...
>>>> 
>>>> Also, the sets of examples are updated, showing examples linked and not linked
>>>> to JDK API docs
>>>> http://cr.openjdk.java.net/~jjg/amber-records/examples/api-with-link/
>>>> http://cr.openjdk.java.net/~jjg/amber-records/examples/api-no-link/
>>> The API docs should show all records as final, regardless of whether or not the
>>> final keywords appears in the source code. ( I’m not sure that this is
>>> currently the case in the changes ).
>>> 
>>> Additionally, ( something that I forgot previously ) I think that the API doc
>>> for all nested records should show them as static, regardless of whether or not
>>> the static keyword appears in the source code. ( A nested record is implicitly
>>> static  ).
>>> 
>>> -Chris.
>> 
>> Chris,
>> 
>> Thanks for the comment. I'll check with the experts on this. While it is true
>> that records are implicitly static final, javadoc does not show implicit
>> modifiers in other similar contexts, like interfaces.
>> 
>> -- Jon