Improving compiler messages for preview API

[Jonathan Gibbons]

On 8/2/19 5:07 PM, Alex Buckley wrote:
> Hi Joe,
>
> On 6/20/2019 10:18 AM, Joe Darcy wrote:> Time is late in JDK 13, but 
> for, say, JDK 14 it may be reasonable to add
>> a java.lang.Preview annotation type to mark preview API elements 
>> rather than relying on overloading the deprecation mechanism. Such an 
>> annotation type would be @Documented and applicable to the sort of 
>> declarations @Deprecated can be applied to.
>
> I think @Preview is the right way to go for JDK 14+. It would underpin 
> a number of scenarios where we wish to call developers' attention to 
> preview features:
>
> 1. In javadoc -- A casual reader of String::stripIndent's javadoc 
> should realize that this method is special: its association with a 
> preview feature (text blocks) means that it might change or go away in 
> the next release without going through a deprecate-and-wait cycle like 
> normal Java SE methods. An @Documented annotation such as @Preview 
> would let the standard doclet give special visual treatment to 
> types/fields/methods ("API elements") associated with preview features.
>
> 2. At compile time -- If you compile with --enable-preview, then any 
> source code reference to an API element associated with a preview 
> feature should generate a (non-suppressible) warning. This warning, 
> which would require JLS support, would be distinct from deprecation 
> warnings; we would then be in a position in JDK 14+ to drop the 
> terminally-deprecated-at-birth scheme adopted in JEP 12 as a stopgap.
>
> 3. At run time -- If you compile without --enable-preview, and the 
> source code refers to an API element associated with a preview 
> feature, then javac could give a (non-suppressible) warning and _mark 
> the class file as depending on preview features_. It is important to 
> handle this scenario firmly because the API element might be gone in a 
> later release. Annotating the type/method gives grounds for javac to 
> explain what's going on: "This method is marked @Preview; your class 
> file is now preview-feature dependent."
>
> The annotation type that you defined in the webrev 
> (j.l.a.PreviewFeature) looks good. However, I don't think the 
> `release` element is needed. The API in SE $N is what it is; API 
> elements associated with a preview feature are there because a JEP put 
> them there. The `release` element would always be the current JDK 
> release.
>
> Alex


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.

-- Jon