RFR: JDK-8250768: javac should be adapted to changes in JEP 12

[Hannes Wallnöfer]

On Mon, 19 Oct 2020 14:09:51 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> This is an update to javac and javadoc, to introduce support for Preview APIs, and generally improve javac and javadoc
>> behavior to more closely adhere to JEP 12.
>> The notable changes are:
>> 
>>  * adding support for Preview APIs (javac until now supported primarily only preview language features, and APIs
>>    associated with preview language features). This includes:
>>      * the @PreviewFeature annotation has boolean attribute "reflective", which should be true for reflective Preview APIs,
>>        false otherwise. This replaces the existing "essentialAPI" attribute with roughly inverted meaning.
>>      * the preview warnings for preview APIs are auto-suppressed as described in the JEP 12. E.g. the module that declares the
>>        preview API is free to use it without warnings
>>  * improving error/warning messages. Please see [1] for a list of cases/examples.
>>  * class files are only marked as preview if they are using a preview feature. [1] also shows if a class file is marked as
>>    preview or not.
>>  * the PreviewFeature annotation has been moved to jdk.internal.javac package (originally was in the jdk.internal package).
>>  * Preview API in JDK's javadoc no longer needs to specify @preview tag in the source files. javadoc will auto-generate a
>>    note for @PreviewFeature elements, see e.g. [2] and [3] (non-reflective and reflective API, respectively). A summary of
>>    preview elements is also provided [4]. Existing uses of @preview have been updated/removed.
>>  * non-JDK javadoc is also enhanced to auto-generate preview notes for uses of Preview elements, and for declaring
>>    elements using preview language features [5].
>>  
>>  Please also see the CSR [6] for more information.
>>  
>>  [1] http://cr.openjdk.java.net/~jlahoda/8250768/JEP12-errors-warnings-v6.html
>>  [2] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.base/java/lang/Record.html
>>  [3]
>>  http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.compiler/javax/lang/model/element/RecordComponentElement.html
>>  [4] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/preview-list.html [5]
>>  http://cr.openjdk.java.net/~jlahoda/8250768/test.javadoc.00/ [6] https://bugs.openjdk.java.net/browse/JDK-8250769
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2238:
> 
>> 2236:             if (previewTree != null) {
>> 2237:                 previewDiv.add(new HtmlTree(TagName.A).put(HtmlAttr.ID, "preview")
>> 2238:                                                       .add(new
>> RawHtml(utils.getPreviewTreeSummaryOrDetails(previewTree, false))));
> 
> The `id` attribute needs to be unique within the page, so in addition to make the value not a valid java identifier (as
> @jonathan-gibbons pointed out in a comment elsewhere) we need to support multiple preview ids per page. One way to do
> this would be to add the element name to the id value, e.g. `preview-<element name>`.

Of course the element name won't do for overloaded methods and constructors... `Links#getAnchor(ExecutableElement)`
should be used for those.

-------------

PR: https://git.openjdk.java.net/jdk/pull/703