RFR: JDK-8226585: Improve javac messages for using a preview API

[Joe Darcy]

Hi Jan,

For future work, consider having a "Preview Methods" tag alongside 
static, instance, deprecated, etc.

Cheers,

-Joe

On 10/3/2019 2:57 AM, Jan Lahoda wrote:
> Hi,
>
> This is a continuation of Joe's patch from here:
> https://mail.openjdk.java.net/pipermail/compiler-dev/2019-June/013498.html 
>
>
> APIs associated with preview features are split into two groups: 
> essential and non-essential. These are marked with an JDK-internal 
> annotation, PreviewFeature, and a tag in the javadoc, @preview. The 
> javac follows the PreviewFeature annotation, and produces either 
> warnings or errors for the usages of such APIs. For the @preview tag, 
> there is a taglet in the JDK build that adds the content of the tag 
> into the documentation. The first part of the @preview's text goes 
> into the summary, the second part goes into the detailed description.
>
> For build, a tricky problem is that the jdk.compiler module uses the 
> PreviewFeature annotation as well, but that is not in the bootstrap 
> JDK. So, for the intermediate langtools build, the PreviewFeature 
> annotation is copied from java.base.
>
> Proposed webrev:
> http://cr.openjdk.java.net/~jlahoda/8226585/webrev.00/
>
> Javadoc with the change:
> http://cr.openjdk.java.net/~jlahoda/8226585/docs.00/api/index.html
>
> See for example:
> http://cr.openjdk.java.net/~jlahoda/8226585/docs.00/api/java.base/java/lang/String.html 
>
> http://cr.openjdk.java.net/~jlahoda/8226585/docs.00/api/jdk.compiler/com/sun/source/tree/CaseTree.html 
>
>
> JBS:
> https://bugs.openjdk.java.net/browse/JDK-8226585
>
> CSR:
> https://bugs.openjdk.java.net/browse/JDK-8231411
>
> Feedback is welcome!
>
> Thanks,
>     Jan