Improving compiler messages for preview API

[Jonathan Gibbons]

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.

-- Jon