[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-compiler-dev
Subject:    Re: RFR: JDK-8235352: java.lang.runtime.package-info should be annotated with @PreviewFeature
From:       Alex Buckley <alex.buckley () oracle ! com>
Date:       2020-01-09 0:16:38
Message-ID: e8998cd5-5e44-2c36-74a5-ff4522572105 () oracle ! com
[Download RAW message or body]

The excitingly-named java.lang.runtime package has been a long time 
coming. In its absence, LambdaMetaFactory and StringConcatFactory had to 
go in java.lang.invoke, which confused the purpose of *that* package. 
Still, with only record-related functionality in java.lang.runtime 
(nothing is being moved from j.l.i to j.l.r), it's right to be very 
clear that j.l.r isn't final and permanent in 14. Making it stand out in 
the module summary of java.base achieves that.

Separately, both j.l.i and j.l.r have a description whose style is wrong 
and whose content is vague. I recommend:

- java.lang.invoke: "Provides classes for controlling dynamic linkage in 
the Java Virtual Machine."  [This is a user-level API, albeit for very 
advanced users. Such APIs in java.base are usually described as 
providing classes for XYZ.]

- java.lang.runtime: "Supports the implementation of Java programs on 
the Java Virtual Machine."  [This is a tool-level API, not a user-level 
API, so it doesn't "provide classes" for XYZ but rather "supports" XYZ.]

And for the record:

- java.lang.annotation: "Provides annotations used to describe 
fundamental properties of annotation types."  [e.g. where is an 
annotation type applicable? is it repeatable? and so on. I'm ignoring 
java.lang.annotation.Native because it isn't part of the "science" of 
annotation types; it's just an "application" of the metadata facility, 
like @Deprecated, with meaning only to a particular tool, so it should 
be in java.lang.]

Alex

On 1/8/2020 3:13 PM, Jonathan Gibbons wrote:
> Vicente,
> 
> A qualified-OK.
> 
> I find it curious to declare the package as a preview feature, as 
> compared to the class in it. I agree that ObjectMethods should be so 
> marked, so there is no issue there.
> 
> So my OK is conditional on there being some decision recorded somewhere 
> that we want to do this;   if there is such a decision, then I agree you 
> have implemented the decision in an acceptable way.
> 
> -- Jon
> 
> On 1/8/20 2:58 PM, Vicente Romero wrote:
>> ok good, are you OK with the change?
>>
>> Vicente
>>
>> On 1/8/20 5:16 PM, Jonathan Gibbons wrote:
>>> Yeah, that's the specdiff, not the underlying API, but I can see the 
>>> info I was looking for. Thanks.
>>>
>>> -- Jon
>>>
>>> On 1/8/20 2:13 PM, Vicente Romero wrote:
>>>> sure, please find it at [1]
>>>>
>>>> Thanks,
>>>> Vicente
>>>>
>>>> [1] http://cr.openjdk.java.net/~vromero/8235352/specdiff.runtime/
>>>>
>>>> On 1/8/20 4:17 PM, Jonathan Gibbons wrote:
>>>>> Vicente,
>>>>>
>>>>> Given that you have put the {@preview} at the beginning, how well 
>>>>> does this interact with javadoc and javadoc's handling of the first 
>>>>> sentence in summary contexts? Could you generate docs and post the 
>>>>> API bundle along with the webrev.
>>>>>
>>>>> -- Jon
>>>>>
>>>>>
>>>>> On 01/08/2020 01:11 PM, Vicente Romero wrote:
>>>>>> Please review this simple fix which is adding the @PreviewFeature 
>>>>>> and related doc to, new for records, file 
>>>>>> java/lang/runtime/package-info.java. Webrev is at [1] and JIRA 
>>>>>> issue at [2]
>>>>>>
>>>>>> Thanks,
>>>>>> Vicente
>>>>>>
>>>>>> [1] http://cr.openjdk.java.net/~vromero/8235352/webrev.00/
>>>>>> [2] https://bugs.openjdk.java.net/browse/JDK-8235352
>>>>>
>>>>
>>
[prev in list] [next in list] [prev in thread] [next in thread]