Improving compiler messages for preview API

[Jonathan Gibbons]

On 8/5/19 11:40 AM, Alex Buckley wrote:
> On 8/5/2019 11:19 AM, Jonathan Gibbons wrote:
>> On 08/05/2019 11:07 AM, Jonathan Gibbons wrote:
>>> On 08/05/2019 10:52 AM, Alex Buckley wrote:
>>>> On 8/5/2019 10:40 AM, Jonathan Gibbons wrote:
>>>>> What are the arguments for and against using a public Java SE 
>>>>> annotation for this (e.g. j.l.a.PreviewFeature) when the only 
>>>>> reasonable/expected usage is within Java SE and the JDK 
>>>>> implementation. There's a tiny tiny code smell defining an 
>>>>> annotation type that no other users of Java SE will ever use. That 
>>>>> being said, I guess it will enable non-JDK tools to behave 
>>>>> appropriately when such an annotation is found.
>>>>
>>>> Some preview language features depend inexorably on APIs, so those 
>>>> APIs need to be in java.* (e.g. String::stripIndent for text blocks).
>>>>
>>>> Use of those APIs when preview features are not enabled is 
>>>> extremely dangerous, because the APIs might change or disappear 
>>>> depending on the fate of the associated preview feature.
>>>>
>>>> Leaving the developer notification up to individual compilers is 
>>>> inadequate. JEP 12 already mandates a policy for highlighting the 
>>>> changeability of these APIs -- terminal deprecation at birth. 
>>>> Conveniently, that required no JLS or compiler changes.
>>>>
>>>> Joe has made a number of arguments, that I hope he will record in 
>>>> JDK-8226585, against using terminal-deprecation-at-birth. Per this 
>>>> thread, a compile-time error is even better than a warning when the 
>>>> developer fails to enable preview features.
>>>>
>>>> The only way to get all Java compilers to give an error is with a 
>>>> JLS change and a Java SE annotation.
>>>>
>>>> It would not be an error to _apply_ this annotation to declarations 
>>>> outside the Java SE API, but compilers would be required to give an 
>>>> error only when code uses an annotated element which is part of the 
>>>> Java SE API.
>>>>
>>>> Alex
>>>
>>> Your last point is a good one, and duly noted.
>>>
>>> To the rest, yes, while other users may not want to *use* the 
>>> annotation type, it is definitely of interest to them, and to the 
>>> tools that they may use, that the annotation has been provided on 
>>> API related to preview features.
>>>
>>> -- Jon
>>
>> I note that I would want to use the annotation on non-Java SE API, 
>> and the com.sun.source.tree API in particular, where we define the 
>> compiler AST classes, including any new elements for preview features.
>
> To be clear about this case, a compiler would be required to do 
> nothing about the use of such an API -- no warning, no error. The 
> definition of java.lang.annotation.PreviewFeature will refer to 
> marking "essential" and "reflective" Java SE APIs connected with 
> preview features; the annotation has no meaning if applied to a 
> non-Java SE API.
>
> Alex


Hmm. Understood, but disappointed.  That's a fairly big use case you're 
eliminating (going by the number of declared elements).

-- Jon