Improving compiler messages for preview API

[Jonathan Gibbons]

Joe,

The code changes as presented look good.  A slightly more sophisticated 
solution would be to introduce a new MandatoryWarningHandler similar to 
"removalHandler", which would allow fewer (but not zero) messages when 
code is using preview API "a lot".  Maybe that's a future possibility, 
but the proposed informative-but-not-scary messages are a definite 
improvement.

-- Jon


On 06/21/2019 10:38 AM, Joe Darcy wrote:
>
> 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/94521b79/attachment-0001.html>