Improving compiler messages for preview API

[Jonathan Gibbons]

On 8/8/19 5:54 PM, Alex Buckley wrote:
> On 8/8/2019 5:08 PM, Maurizio Cimadamore wrote:
>> Ideally, what you want is to add @Preview in a non-exported package, 
>> (pretty much as @ForceInline) so that it can be used wherever 
>> (including non SE APIs) in the JDK (provided the package is 
>> qualified-exported accordingly) - and that takes care of the fact 
>> that the annotation could not be placed on code outside of the JDK.
>
> This was Joe's initial intent -- jdk.internal.Preview to be precise -- 
> but it would be inappropriate for such an annotation type to be 
> @Documented and show up in the javadoc on String::stripIndent. There 
> is also the other problem you raise:

It does not need to be @Documented.

We could use a combination of the current deprecation mechanism combined 
with a JDK-internal annotation to modify the text of the warnings 
generated by javac and the text generated by javadoc.


>> what the compiler should do when encountering a method marked with 
>> @Preview, if @Preview itself is not part of the Java SE API - meaning 
>> a spec (e.g. JLS) cant really refer to it. But, is there a need for 
>> the spec to refer to it? Could we get away with saying that "there 
>> must be a way to mark preview API methods" without saying _what_ way 
>> that is?
>
> The JLS is not and cannot be "open". In order for the JLS to mandate 
> an error (or even a warning) about use of a preview-feature-connected 
> API, the Java SE Platform has to be the ultimate authority for 
> identifying such APIs. The identification must be normative, though it 
> can be lightweight -- a simple mention of "Text Blocks (JEP 355)" in 
> the Platform JSR is enough to get String::stripIndent on the list. 
> Now, I would be mostly OK with dropping the SE-defined @PreviewFeature 
> annotation if compiler vendors were eager to incorporate knowledge of 
> such Platform-identified APIs, but it was made clear (internally) that 
> javac did not want to do this. So, we have a marker annotation (in 
> SE), and we have some consensus about wanting an error when identified 
> APIs (in SE) are used without enabling preview features, and those two 
> design choices work together. Let's not spend more time pondering how 
> non-SE APIs can play in the preview sandpit please.
>
> Alex

In the discussion about having a list of preview APIs, the context was a 
list hard-coded into the compiler source code. If the list could be 
determined "dynamically" at JDK-build time, such as by an annotation 
processor, that might be different.

-- Jon