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

[Jan Lahoda]

Hi Joe,

Thanks for the suggestion, but I don't think we can do it using Taglets 
- as far as I know, Taglets cannot add tabs to the method listing. We 
would either need to modify javadoc, or (maybe) have a special doclet 
for JDK documentation.

Jan

On 04. 10. 19 7:08, Joe Darcy wrote:
> 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