Improving compiler messages for preview API

[Jonathan Gibbons]

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