Improving compiler messages for preview API

[Alex Buckley]

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