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

[Maurizio Cimadamore]

On Fri, 16 Oct 2020 15:20:03 GMT, Jan Lahoda <jlahoda 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

I've done a quick pass over the javac changes, things look good, apart from some (minor) comments.

I'm a bit worried about the scalability of the output in this page:

http://cr.openjdk.java.net/~jlahoda/8250768/test.javadoc.00/use/Factory.html

E.g. if the types which use preview features are a lot (e.g. 50), what would the text inside the black box look like?

src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Enter.java line 108:

> 106:     Modules modules;
> 107:     JCDiagnostic.Factory diags;
> 108:     Preview preview;

Are these changes spurious?

src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java line 3565:

> 3563:         }
> 3564:     }
> 3565:     private boolean declaredUsingPreviewFeature(Symbol sym) {

I wonder, maybe this routine should go in Preview.java?

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java line 2649:

> 2647:         }
> 2648:         if (isRecordStart() && allowRecords) {
> 2649:             checkSourceLevel(Feature.RECORDS);

Is this change really related to the JEP 12?

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java line 3713:

> 3711:             return classDeclaration(mods, dc);
> 3712:         } if (isRecordStart()) {
> 3713:              checkSourceLevel(Feature.RECORDS);

Same here

src/jdk.compiler/share/classes/com/sun/tools/javac/util/RawDiagnosticFormatter.java line 166:

> 164:             s = "compiler.misc.tree.tag." + StringUtils.toLowerCase(((Tag) arg).name());
> 165:         } else if (arg instanceof Source && arg == Source.DEFAULT &&
> 166:                 CODES_NEEDING_SOURCE_NORMALIZATION.contains(diag.getCode())) {

Nice trick to keep raw output constant across versions :-)

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

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