Aligning compiler messages for using preview API with preview language features?

[Joe Darcy]

Hello,

On 7/16/2019 4:14 PM, Alex Buckley wrote:
> On 7/2/2019 5:33 PM, Joe Darcy wrote:
>> Assuming some mechanism to implement a predicate identifying a preview
>> API (presence of an annotation, side table in the compiler, etc.), the
>> messages for preview APIs could be routed through the same
>> previewHandler used to process preview language features.
>>
>> The summary message
>>
>>      Note: Test.java uses preview language features.
>>      Note: Recompile with -Xlint:preview for details.
>>
>> could then be replaced with something like
>>
>>      Note: Test.java uses preview language features and/or preview API
>> elements.
>>      Note: Recompile with -Xlint:preview for details.
>>
>> or more specialize variants for the particular combinations of a least
>> one flavor of preview functionality being used.
>
> If this is strictly about the wording of the summary message, then I 
> would prefer to stay away from the term "preview API" until such time 
> as there is a java.lang.Preview annotation type which supercedes 
> terminal-deprecation-at-birth. Perhaps:
>
>   Note: Test.java uses preview language features and/or
>         APIs connected with preview language features.
>   Note: Recompile ...
>
> And if you compile with --enable-preview but (say) you don't use text 
> blocks, you just call String::stripIndent directly:
>
>   Note: Test.java uses APIs connected with preview language features.
>   Note: Recompile ...


Yes; getting the compiler messages to distinguish between just "preivew 
API" usage (modulo wording above), preview language features, or both 
should be simple enough using distinct methods to record the 
preview-related usages of different kinds.

There are at least two possible versions of Preview annotation type:

1) One that supplements @Deprecated(forRemoval=true) and only suppresses 
the deprecation warning if --enable-preview is used.

2) One that replaces @Deprecated(forRemoval=true) for preview-related 
APIs and generates differentiated messages based on the status of 
--enable-preview.

If the distinct annotation type is added, I'd prefer the latter; 
although it would (presumably) require some JLS spec work. I think the 
former option would still be an improvement over the current warning 
generation situation.

Cheers,

-Joe