Improving compiler messages for preview API

[Joe Darcy]

Hello,

In JDK 13, as part of the text blocks preview feature 
(http://openjdk.java.net/jeps/355), there are now several preview API 
methods in java.lang.String. Preview API handling is discussed in JEP 
12: "Preview Language and VM Features" (http://openjdk.java.net/jeps/12):

> This JEP does not propose a new mechanism for flagging "preview APIs", 
> but rather, proposes to reuse the deprecation mechanism:
>
> 1.
>
>     Essential and reflective APIs that are connected with a preview
>     feature should be terminally deprecated at birth, that is,
>     annotated |@Deprecated(forRemoval=true, since=...)| when they are
>     introduced.
>
Accordingly, the declaration of the three preview API methods includes 
javadoc and annotations like:

> + * @since 13 + * + * @deprecated This method is associated with text 
> blocks, a preview language feature. + * Text blocks and/or this method 
> may be changed or removed in a future release. + */ + 
> @Deprecated(forRemoval=true, since="13") + public String stripIndent()

Using JDK 13 b25 to compile code using both the preview language feature 
and preview API

public class Test {
     public static void main(String... args) {
         String message = """
                          Hello, world.
                          """;
         System.out.println(message.stripIndent()); //String.stripIndent 
in preview
     }
}

the resulting compiler messages are

  ../jdk-13/bin/javac --release 13 --enable-preview Test.java
Test.java:7: warning: [removal] stripIndent() in String has been 
deprecated and marked for removal
         System.out.println(message.stripIndent());
                                   ^
Note: Test.java uses preview language features.
Note: Recompile with -Xlint:preview for details.
1 warning

The removal warning for using the preview API element stripIndent is a 
bit harsh, after all the compilation has explicitly enabled preview 
features. However, strictly speaking such a warning is required by the 
JLS for a terminally deprecated item. [1]

I think more reasonable messaging for this program would be something like:

     Note: Test.java uses preview language features and preview API 
elements.
     ...

or just omitting mention of using preview API elements if compiling 
under --enable-preview. Emitting a warning for using preview API 
elements when *not* running under --enable-preview is important for the 
reasons discussed in JEP 12.

Refined error messages for preview API elements could be given by the 
compiler if preview API elements were marked in some way to reliably 
distinguish them from other terminally deprecated items.

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 an applicable to the sort of 
declarations @Deprecated can be applied to.

If this kind of approach seems reasonable, core-libs will be brought in too.

Comments?

Cheers,

-Joe

[1] 
https://docs.oracle.com/javase/specs/jls/se12/html/jls-9.html#jls-9.6.4.6

> A Java compiler must produce a /removal warning/ when a terminally 
> deprecated program element is used (overridden, invoked, or referenced 
> by name) in the declaration of a program element (whether explicitly 
> or implicitly declared), unless:
>
>  *
>
>      The use is within a declaration that is annotated to suppress
>     removal warnings; or
>
>  *
>
>     The use and declaration are both within the same outermost class; or
>
>  *
>
>      The use is within an |import| declaration that imports the
>     terminally deprecated type or member.
>
>  *
>
>     The use is within an |exports| or |opens| directive.
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20190620/d252c621/attachment.html>