Improving compiler messages for preview API

[Joe Darcy]

PS Prototype version of what this sort of message improvement could look 
like, initially coded with a JDK-internal annotation type as opposed to 
one in java.lang:

     http://cr.openjdk.java.net/~darcy/8226585.0/

When compiling the code

public class Test {
     public static void main(String... args) {
         String message = "Hello, world.";

         System.out.println(message.stripIndent()); //String.stripIndent 
in preview
     }
}

the revised compiler gives the following messages

# Without --enable-preview

 > javac --release 13 Test.java
Test.java:5: warning: [removal] stripIndent() in String has been 
deprecated and marked for removal as a preview API
         System.out.println(message.stripIndent()); //String.stripIndent 
in preview
                                   ^
1 warning

# With --enable-preview

 > javac --release 13 --enable-preview Test.java
Test.java:5: Note: stripIndent() in String is a preview API and may be 
removed in a future release
         System.out.println(message.stripIndent()); //String.stripIndent 
in preview
                                   ^
All langtools tests pass with the patch applied.

Cheers,

-Joe

On 6/20/2019 10:18 AM, Joe Darcy wrote:
>
> 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/20190621/f6fedb80/attachment.html>