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

[Alex Buckley]

I saw Jon had a comment about terminology in jdk.javadoc -> 
resources/standard.properties, lines 280-290.

Those lines look good to me. For javadoc's purposes, there are (a) 
preview features of the Java platform which are either (b) preview 
features of the Java language or (c) [reflective] preview APIs [of the 
Java platform]. When we refer to one of the (b) features, it's enough to 
mention "the Java language" and assume that people know the language, 
like the APIs, is a part of the platform.

In theory, it would be right for javadoc output to be specific about 
which release of the Java language/platform defines the preview features 
in question. This is especially true when `javadoc` is run over user 
code (i.e., not JDK code) that happens to use preview language features. 
Referring to a specific release is easier with "Java SE" phrasing than 
"the Java platform" phrasing, which is why jdk.compiler -> 
resources/compiler.properties says "preview features of Java SE {1}". 
All that said, I think the jdk.javadoc -> resources/standard.properties 
file is fine as-is. Anyone running `javadoc` should know which JDK 
release they're getting it from, and anyone reading javadoc output must 
have some sense of the era that the output dates from.

Alex

On 11/2/2020 10:15 AM, Jan Lahoda 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
> 
> Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 46 commits:
> 
>   - Removing trailing whitespace.
>   - Merging master into JDK-8250768.
>   - Updating tests after records are a final feature.
>   - Fixing tests.
>   - Finalizing removal of record preview hooks.
>   - Merging master into JDK-8250768
>   - Reflecting review comments.
>   - Merge branch 'master' into JDK-8250768
>   - Removing unnecessary cast.
>   - Using a more correct way to get URLs.
>   - ... and 36 more: https://git.openjdk.java.net/jdk/compare/d93e3a7d...2e403900
> 
> -------------
> 
> Changes: https://git.openjdk.java.net/jdk/pull/703/files
>   Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=05
>    Stats: 3012 lines in 142 files changed: 2521 ins; 260 del; 231 mod
>    Patch: https://git.openjdk.java.net/jdk/pull/703.diff
>    Fetch: git fetch https://git.openjdk.java.net/jdk pull/703/head:pull/703
> 
> PR: https://git.openjdk.java.net/jdk/pull/703
>