From vromero at openjdk.java.net Thu Oct 1 01:31:04 2020 From: vromero at openjdk.java.net (Vicente Romero) Date: Thu, 1 Oct 2020 01:31:04 GMT Subject: RFR: 8246774: implementing Record Classes as a standard feature in Java [v9] In-Reply-To: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> Message-ID: <0aKjS2ruCGPqJsSjll3RsknZpCuGsAkrQaANwVqPTMs=.b9628de2-6f3e-41d0-9c59-6b85dd6d71f5@github.com> > Co-authored-by: Vicente Romero > Co-authored-by: Harold Seigel > Co-authored-by: Jonathan Gibbons > Co-authored-by: Brian Goetz > Co-authored-by: Maurizio Cimadamore > Co-authored-by: Joe Darcy > Co-authored-by: Chris Hegarty > Co-authored-by: Jan Lahoda Vicente Romero has updated the pull request incrementally with one additional commit since the last revision: remove unnecessary jtreg tags from tests, remove othervm etc when applicable ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/290/files - new: https://git.openjdk.java.net/jdk/pull/290/files/76e3d278..7501148d Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=08 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=07-08 Stats: 102 lines in 54 files changed: 33 ins; 19 del; 50 mod Patch: https://git.openjdk.java.net/jdk/pull/290.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/290/head:pull/290 PR: https://git.openjdk.java.net/jdk/pull/290 From vromero at openjdk.java.net Thu Oct 1 01:33:58 2020 From: vromero at openjdk.java.net (Vicente Romero) Date: Thu, 1 Oct 2020 01:33:58 GMT Subject: RFR: 8246774: implementing Record Classes as a standard feature in Java [v3] In-Reply-To: References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> Message-ID: On Wed, 30 Sep 2020 08:54:14 GMT, Chris Hegarty wrote: >> test/langtools/tools/javac/records/LocalStaticDeclarations.java line 33: >> >>> 31: * jdk.compiler/com.sun.tools.javac.util >>> 32: * @build combo.ComboTestHelper >>> 33: * @compile LocalStaticDeclarations.java >> >> This, and other, explicit at compile tags could be elided, no? The test source file will be implicitly compiled by the >> at run tag. I believe that the explicit at compile tag was added original so that the enable preview and source version >> options could be passed to javac - neither of which are needed any more. > > Does this test need an @run tag rather than an @compile tag ? ( the @run with implicitly compile the source file, > before running it ) @ChrisHegarty I have created commit [7501148](https://github.com/openjdk/jdk/pull/290/commits/7501148dd4c21847699a84d6dc5ef100d993b78d) to address this issue, thanks ------------- PR: https://git.openjdk.java.net/jdk/pull/290 From chegar at openjdk.java.net Thu Oct 1 09:32:03 2020 From: chegar at openjdk.java.net (Chris Hegarty) Date: Thu, 1 Oct 2020 09:32:03 GMT Subject: RFR: 8246774: implementing Record Classes as a standard feature in Java [v9] In-Reply-To: <0aKjS2ruCGPqJsSjll3RsknZpCuGsAkrQaANwVqPTMs=.b9628de2-6f3e-41d0-9c59-6b85dd6d71f5@github.com> References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> <0aKjS2ruCGPqJsSjll3RsknZpCuGsAkrQaANwVqPTMs=.b9628de2-6f3e-41d0-9c59-6b85dd6d71f5@github.com> Message-ID: On Thu, 1 Oct 2020 01:31:04 GMT, Vicente Romero wrote: >> Co-authored-by: Vicente Romero >> Co-authored-by: Harold Seigel >> Co-authored-by: Jonathan Gibbons >> Co-authored-by: Brian Goetz >> Co-authored-by: Maurizio Cimadamore >> Co-authored-by: Joe Darcy >> Co-authored-by: Chris Hegarty >> Co-authored-by: Jan Lahoda > > Vicente Romero has updated the pull request incrementally with one additional commit since the last revision: > > remove unnecessary jtreg tags from tests, remove othervm etc when applicable Marked as reviewed by chegar (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/290 From jlahoda at openjdk.java.net Tue Oct 6 10:39:46 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Tue, 6 Oct 2020 10:39:46 GMT Subject: RFR: 8253354: A jshell command to open desktop browser with specific javadoc query Message-ID: Adding a new command "/doc " to JShell. This command opens the javadoc URL for the given element. A new setting, /set browser, is introduced to actually set the browser that should be used to open the URL. If none specified, JShell tries to use Desktop.browse (which may fail on some platforms). ------------- Commit messages: - Cleanup. - Fixing tests. - Cleanup. - Cleanup. - Cleanup. - Cleanup whitespaces. - Cleanup, javadoc. - Cleanup. - Sketch of a new /doc command for JShell. Changes: https://git.openjdk.java.net/jdk/pull/521/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=521&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8253354 Stats: 614 lines in 9 files changed: 526 ins; 10 del; 78 mod Patch: https://git.openjdk.java.net/jdk/pull/521.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/521/head:pull/521 PR: https://git.openjdk.java.net/jdk/pull/521 From vromero at openjdk.java.net Wed Oct 7 13:36:29 2020 From: vromero at openjdk.java.net (Vicente Romero) Date: Wed, 7 Oct 2020 13:36:29 GMT Subject: RFR: 8246774: implementing Record Classes as a standard feature in Java [v10] In-Reply-To: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> Message-ID: > 8246774: implementing Record Classes as a standard feature in Java Vicente Romero has updated the pull request incrementally with one additional commit since the last revision: removing unused jcod file ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/290/files - new: https://git.openjdk.java.net/jdk/pull/290/files/7501148d..1bcda595 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=09 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=08-09 Stats: 256 lines in 1 file changed: 0 ins; 256 del; 0 mod Patch: https://git.openjdk.java.net/jdk/pull/290.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/290/head:pull/290 PR: https://git.openjdk.java.net/jdk/pull/290 From vromero at openjdk.java.net Mon Oct 12 21:35:36 2020 From: vromero at openjdk.java.net (Vicente Romero) Date: Mon, 12 Oct 2020 21:35:36 GMT Subject: RFR: 8246774: implementing Record Classes as a standard feature in Java [v11] In-Reply-To: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> Message-ID: > 8246774: implementing Record Classes as a standard feature in Java Vicente Romero has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains ten commits: - Merge branch 'master' into JDK-8246774 - removing unused jcod file - remove unnecessary jtreg tags from tests, remove othervm etc when applicable - adding missing changes to some tests - modifiying @since from 14 to 16 - Remove preview args from ObjectMethodsTest - Remove preview args from record serialization tests - removing the javax.lang.model related code to be moved to a separate bug - 8246774: Record Classes (final) implementation Co-authored-by: Vicente Romero Co-authored-by: Harold Seigel Co-authored-by: Jonathan Gibbons Co-authored-by: Brian Goetz Co-authored-by: Maurizio Cimadamore Co-authored-by: Joe Darcy Co-authored-by: Chris Hegarty Co-authored-by: Jan Lahoda ------------- Changes: https://git.openjdk.java.net/jdk/pull/290/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=10 Stats: 856 lines in 109 files changed: 64 ins; 552 del; 240 mod Patch: https://git.openjdk.java.net/jdk/pull/290.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/290/head:pull/290 PR: https://git.openjdk.java.net/jdk/pull/290 From jlahoda at openjdk.java.net Fri Oct 16 15:27:22 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Fri, 16 Oct 2020 15:27:22 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 Message-ID: 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 ------------- Commit messages: - Fixing tests. - Various cleanup. - The Preview taglet is not needed anymore. - There is not jdk.internal package anymore - No, jdk.incubator.vector does not need jdk.internal package. - Merging master into JDK-8250768 - Fixing tests. - Adding forgotten files. - Updating build. - Post-merge fix. - ... and 19 more: https://git.openjdk.java.net/jdk/compare/9359ff03...efb37a9b Changes: https://git.openjdk.java.net/jdk/pull/703/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8250768 Stats: 3179 lines in 158 files changed: 2487 ins; 410 del; 282 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 From mcimadamore at openjdk.java.net Fri Oct 16 16:12:11 2020 From: mcimadamore at openjdk.java.net (Maurizio Cimadamore) Date: Fri, 16 Oct 2020 16:12:11 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 In-Reply-To: References: Message-ID: <5xE8fziHH9n04bSHhODnOB9On3t_zGz-JY0gJhVhP74=.0c79430f-fac0-44f9-82be-40ef2f94a0d9@github.com> On Fri, 16 Oct 2020 15:20:03 GMT, 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 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 From erikj at openjdk.java.net Fri Oct 16 16:50:12 2020 From: erikj at openjdk.java.net (Erik Joelsson) Date: Fri, 16 Oct 2020 16:50:12 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 In-Reply-To: References: Message-ID: On Fri, 16 Oct 2020 15:20:03 GMT, 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 Build changes look good. ------------- Marked as reviewed by erikj (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/703 From jjg at openjdk.java.net Fri Oct 16 17:26:10 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 16 Oct 2020 17:26:10 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 In-Reply-To: References: Message-ID: On Fri, 16 Oct 2020 15:20:03 GMT, 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 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java line 209: > 207: "sealed".equals(modifiersPart) || "non-sealed".equals(modifiersPart)) { > 208: pre.add(modifiersPart); > 209: pre.add(new HtmlTree(TagName.SUP).add(HtmlTree.A("#preview", contents.previewMark))); This will likely clash with a public field named "preview". You should choose a name for the anchor that is not a Java identifier. Also, in general, it is better to use the `Links` class if possible to create links. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From vromero at openjdk.java.net Sun Oct 18 16:12:22 2020 From: vromero at openjdk.java.net (Vicente Romero) Date: Sun, 18 Oct 2020 16:12:22 GMT Subject: RFR: 8246774: implement Record Classes as a standard feature in Java [v12] In-Reply-To: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> Message-ID: > 8246774: implement Record Classes as a standard feature in Java Vicente Romero has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 10 commits: - Merge branch 'master' into JDK-8246774 - Merge branch 'master' into JDK-8246774 - removing unused jcod file - remove unnecessary jtreg tags from tests, remove othervm etc when applicable - adding missing changes to some tests - modifiying @since from 14 to 16 - Remove preview args from ObjectMethodsTest - Remove preview args from record serialization tests - removing the javax.lang.model related code to be moved to a separate bug - 8246774: Record Classes (final) implementation Co-authored-by: Vicente Romero Co-authored-by: Harold Seigel Co-authored-by: Jonathan Gibbons Co-authored-by: Brian Goetz Co-authored-by: Maurizio Cimadamore Co-authored-by: Joe Darcy Co-authored-by: Chris Hegarty Co-authored-by: Jan Lahoda ------------- Changes: https://git.openjdk.java.net/jdk/pull/290/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=11 Stats: 856 lines in 109 files changed: 72 ins; 562 del; 222 mod Patch: https://git.openjdk.java.net/jdk/pull/290.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/290/head:pull/290 PR: https://git.openjdk.java.net/jdk/pull/290 From vromero at openjdk.java.net Sun Oct 18 16:40:31 2020 From: vromero at openjdk.java.net (Vicente Romero) Date: Sun, 18 Oct 2020 16:40:31 GMT Subject: RFR: 8246774: implement Record Classes as a standard feature in Java [v13] In-Reply-To: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> Message-ID: > 8246774: implement Record Classes as a standard feature in Java Vicente Romero has updated the pull request incrementally with one additional commit since the last revision: removing reference to unused jcod file from test ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/290/files - new: https://git.openjdk.java.net/jdk/pull/290/files/5bfbde59..3e472bc3 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=12 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=290&range=11-12 Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.java.net/jdk/pull/290.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/290/head:pull/290 PR: https://git.openjdk.java.net/jdk/pull/290 From vromero at openjdk.java.net Sun Oct 18 18:58:16 2020 From: vromero at openjdk.java.net (Vicente Romero) Date: Sun, 18 Oct 2020 18:58:16 GMT Subject: Integrated: 8246774: implement Record Classes as a standard feature in Java In-Reply-To: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> References: <48S0UHUnWOQmJO6ErAIDgerNxM4Ibm9anIDZAdcKBp0=.32180f4d-1096-4645-8b23-54aa9f0300fb@github.com> Message-ID: On Mon, 21 Sep 2020 21:30:51 GMT, Vicente Romero wrote: > 8246774: implement Record Classes as a standard feature in Java This pull request has now been integrated. Changeset: c17d5851 Author: Vicente Romero URL: https://git.openjdk.java.net/jdk/commit/c17d5851 Stats: 856 lines in 109 files changed: 72 ins; 562 del; 222 mod 8246774: implement Record Classes as a standard feature in Java Co-authored-by: Vicente Romero Co-authored-by: Harold Seigel Co-authored-by: Chris Hegarty Reviewed-by: coleenp, jlahoda, sspitsyn, chegar ------------- PR: https://git.openjdk.java.net/jdk/pull/290 From hannesw at openjdk.java.net Mon Oct 19 14:12:19 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Mon, 19 Oct 2020 14:12:19 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 In-Reply-To: References: Message-ID: <8uZm9233btN0CTqlw9Na2eH1apGLJsxBO9QUUkzEcoU=.74b1734a-19b9-409e-b1d8-230121993275@github.com> On Fri, 16 Oct 2020 15:20:03 GMT, 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 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-`. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From hannesw at openjdk.java.net Mon Oct 19 14:25:11 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Mon, 19 Oct 2020 14:25:11 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 In-Reply-To: <8uZm9233btN0CTqlw9Na2eH1apGLJsxBO9QUUkzEcoU=.74b1734a-19b9-409e-b1d8-230121993275@github.com> References: <8uZm9233btN0CTqlw9Na2eH1apGLJsxBO9QUUkzEcoU=.74b1734a-19b9-409e-b1d8-230121993275@github.com> Message-ID: On Mon, 19 Oct 2020 14:09:51 GMT, Hannes Walln?fer 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-`. 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 From jlahoda at openjdk.java.net Mon Oct 19 14:52:14 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Mon, 19 Oct 2020 14:52:14 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 In-Reply-To: References: <8uZm9233btN0CTqlw9Na2eH1apGLJsxBO9QUUkzEcoU=.74b1734a-19b9-409e-b1d8-230121993275@github.com> Message-ID: On Mon, 19 Oct 2020 14:22:17 GMT, Hannes Walln?fer wrote: >> 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-`. > > Of course the element name won't do for overloaded methods and constructors... `Links#getAnchor(ExecutableElement)` > should be used for those. Uh, originally, there was only preview section per file, and I didn't fully realize the JDK's javadoc may have multiple such section. I'll work on this. Thanks for the pointer! ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Tue Oct 20 12:15:23 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Tue, 20 Oct 2020 12:15:23 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v2] In-Reply-To: References: Message-ID: > 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 35 commits: - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into JDK-8250768 - More fixing tests. - Fixing tests. - Using unique sections for preview warning sections, as suggested. - Merge branch 'master' into JDK-8250768 - Reflecting review comments. - Fixing tests. - Various cleanup. - The Preview taglet is not needed anymore. - There is not jdk.internal package anymore - ... and 25 more: https://git.openjdk.java.net/jdk/compare/98ec4a67...be1d8651 ------------- Changes: https://git.openjdk.java.net/jdk/pull/703/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=01 Stats: 3206 lines in 156 files changed: 2515 ins; 409 del; 282 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 From jlahoda at openjdk.java.net Tue Oct 20 12:19:12 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Tue, 20 Oct 2020 12:19:12 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v2] In-Reply-To: References: Message-ID: On Fri, 16 Oct 2020 16:47:25 GMT, Erik Joelsson wrote: >> Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The pull request now >> contains 35 commits: >> - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into JDK-8250768 >> - More fixing tests. >> - Fixing tests. >> - Using unique sections for preview warning sections, as suggested. >> - Merge branch 'master' into JDK-8250768 >> - Reflecting review comments. >> - Fixing tests. >> - Various cleanup. >> - The Preview taglet is not needed anymore. >> - There is not jdk.internal package anymore >> - ... and 25 more: https://git.openjdk.java.net/jdk/compare/98ec4a67...be1d8651 > > Build changes look good. I've updated the patch based on the comments: mostly updating the anchors in the javadoc, but also removing the updates to JavacParser, which are only loosely related to the primary focus of this patch, and should possibly be done separately. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From mcimadamore at openjdk.java.net Tue Oct 20 13:40:22 2020 From: mcimadamore at openjdk.java.net (Maurizio Cimadamore) Date: Tue, 20 Oct 2020 13:40:22 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v2] In-Reply-To: References: Message-ID: On Tue, 20 Oct 2020 12:15:23 GMT, 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 35 commits: > - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into JDK-8250768 > - More fixing tests. > - Fixing tests. > - Using unique sections for preview warning sections, as suggested. > - Merge branch 'master' into JDK-8250768 > - Reflecting review comments. > - Fixing tests. > - Various cleanup. > - The Preview taglet is not needed anymore. > - There is not jdk.internal package anymore > - ... and 25 more: https://git.openjdk.java.net/jdk/compare/98ec4a67...be1d8651 javac changes look good ------------- Marked as reviewed by mcimadamore (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/703 From hannesw at openjdk.java.net Wed Oct 21 15:29:19 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 21 Oct 2020 15:29:19 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v2] In-Reply-To: References: Message-ID: On Tue, 20 Oct 2020 12:15:23 GMT, 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 35 commits: > > - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into JDK-8250768 > - More fixing tests. > - Fixing tests. > - Using unique sections for preview warning sections, as suggested. > - Merge branch 'master' into JDK-8250768 > - Reflecting review comments. > - Fixing tests. > - Various cleanup. > - The Preview taglet is not needed anymore. > - There is not jdk.internal package anymore > - ... and 25 more: https://git.openjdk.java.net/jdk/compare/98ec4a67...be1d8651 The javadoc code changes look reasonable, and the preview bits in the generated documentation look good as well. Apart from my inline comments which all address minor issues, there are a few things I don't like around `PreviewListWriter`: its code replication with `DeprecatedListWriter, and it adds things to HtmlDocletWriter and HtmlStyle that I don't think are strictly necessary. However, I wouldn't expect you to know how we like things done in javadoc, so maybe the simplest solution would be for one of us to go over the javadoc bits, either as part of this pull request or (if you prefer to get it integrated rather sooner) as a follow-up task. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3164: > 3162: } > 3163: > 3164: public Set elementFlags(Element el) { It seems like the sole use of this method and the `ElementFlag` enum below is to determine whether a preview warning note should be generated for an element. Is there something that speaks against simplifying it to reflect that purpose, e.g. change its name to `hasPreviewNote` or `hasPreviewContent` and change the return type to `boolean`? Of course that's unless you foresee adding more `ElementFlag` values in the future. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 125: > 123: import static javax.lang.model.element.ElementKind.METHOD; > 124: import static javax.lang.model.element.ElementKind.PACKAGE; > 125: import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; These imports as well as HtmlAttr above aren't used. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/LinkInfoImpl.java line 247: > 245: * The member this link points to (if any). > 246: */ > 247: public Element whereMember; I don't think `whereMember` is a great name (and `where` above is not a great name either). What about naming this `targetMember` or `targetElement`? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlAttr.java line 47: > 45: CLEAR, > 46: COLS, > 47: COLSPAN, I don't think this is used anywhere. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/links/LinkFactory.java line 209: > 207: linkInfo.label = null; > 208: linkInfo.type = bound; > 209: ((LinkInfoImpl) linkInfo).skipPreview = false; I guess it would be nicer to move the `skipPreview` field to `LinkInfo` to avoid that cast. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1314: > 1312: div = HtmlTree.DIV(HtmlStyle.block, result); > 1313: htmltree.add(div); > 1314: } else { I notice that preview code above produces the same HTML output as non-preview code below in the `else` branch. Do we really need the `preview` parameter? ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Fri Oct 23 16:17:58 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Fri, 23 Oct 2020 16:17:58 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v3] In-Reply-To: References: Message-ID: <8Mdv3fmdDrN4fvcQDIFiq72Z4cgs8Xm9cuHhPUgqj5c=.be071ea4-94b8-4841-bfa8-a432424ba2e6@github.com> > 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 incrementally with two additional commits since the last revision: - Using a more correct way to get URLs. - Reflecting review comments. ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/703/files - new: https://git.openjdk.java.net/jdk/pull/703/files/be1d8651..caa4fd34 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=02 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=01-02 Stats: 41 lines in 7 files changed: 5 ins; 14 del; 22 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 From jlahoda at openjdk.java.net Fri Oct 23 16:21:53 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Fri, 23 Oct 2020 16:21:53 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: References: Message-ID: > 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 incrementally with one additional commit since the last revision: Removing unnecessary cast. ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/703/files - new: https://git.openjdk.java.net/jdk/pull/703/files/caa4fd34..461e7d15 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=03 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=02-03 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 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 From jlahoda at openjdk.java.net Fri Oct 23 16:26:39 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Fri, 23 Oct 2020 16:26:39 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v2] In-Reply-To: References: Message-ID: <6VRynO1yt2p2xY5qSooueo-NLlQ-hD6zWJEkfVOXq94=.b95e79ef-9345-4acf-81cb-e4accbd4ed3c@github.com> On Wed, 21 Oct 2020 15:25:59 GMT, Hannes Walln?fer wrote: >> Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 35 commits: >> >> - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into JDK-8250768 >> - More fixing tests. >> - Fixing tests. >> - Using unique sections for preview warning sections, as suggested. >> - Merge branch 'master' into JDK-8250768 >> - Reflecting review comments. >> - Fixing tests. >> - Various cleanup. >> - The Preview taglet is not needed anymore. >> - There is not jdk.internal package anymore >> - ... and 25 more: https://git.openjdk.java.net/jdk/compare/98ec4a67...be1d8651 > > The javadoc code changes look reasonable, and the preview bits in the generated documentation look good as well. > > Apart from my inline comments which all address minor issues, there are a few things I don't like around `PreviewListWriter`: its code replication with `DeprecatedListWriter, and it adds things to HtmlDocletWriter and HtmlStyle that I don't think are strictly necessary. However, I wouldn't expect you to know how we like things done in javadoc, so maybe the simplest solution would be for one of us to go over the javadoc bits, either as part of this pull request or (if you prefer to get it integrated rather sooner) as a follow-up task. I have update the patch based on Hannes' comments. One open question is whether we should have Utils.elementFlags, or just Utils.isPreviewElement. @jonathan-gibbons, any preference? Thanks! ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jjg at openjdk.java.net Fri Oct 23 17:05:40 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 23 Oct 2020 17:05:40 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v2] In-Reply-To: References: Message-ID: On Wed, 21 Oct 2020 12:43:51 GMT, Hannes Walln?fer wrote: >> Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 35 commits: >> >> - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into JDK-8250768 >> - More fixing tests. >> - Fixing tests. >> - Using unique sections for preview warning sections, as suggested. >> - Merge branch 'master' into JDK-8250768 >> - Reflecting review comments. >> - Fixing tests. >> - Various cleanup. >> - The Preview taglet is not needed anymore. >> - There is not jdk.internal package anymore >> - ... and 25 more: https://git.openjdk.java.net/jdk/compare/98ec4a67...be1d8651 > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3164: > >> 3162: } >> 3163: >> 3164: public Set elementFlags(Element el) { > > It seems like the sole use of this method and the `ElementFlag` enum below is to determine whether a preview warning note should be generated for an element. Is there something that speaks against simplifying it to reflect that purpose, e.g. change its name to `hasPreviewNote` or `hasPreviewContent` and change the return type to `boolean`? Of course that's unless you foresee adding more `ElementFlag` values in the future. There's a number of predicates on an element that the doclet might be interested in that could be cached/reified as "flags". Today, we have "preview" and "deprecated" that have similar handling; there have been discussions about handling native methods in a similar fashion. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jjg at openjdk.java.net Fri Oct 23 18:46:49 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 23 Oct 2020 18:46:49 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: References: Message-ID: On Fri, 23 Oct 2020 16:21:53 GMT, 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 incrementally with one additional commit since the last revision: > > Removing unnecessary cast. I have primarily gone through all the javadoc changes. There are three main areas of feedback: 1. The ElementFlag question. We have gone from one kind of element with special treatment (deprecated) to two (deprecated, preview), and there are signs of a third kind coming soon, maybe as early as next year, for work currently being discussed in the Panama project. As the saying goes, three would be one too many. So, I agree `ElementFlag` is underutilized today and could reasonably be removed, but it does seem worthwhile to keep, and it would even be worth increasing its usage soon, such as to combine methods and classes for deprecated elements and preview elements. I'm not sure I can go back into looking at files while typing this message, but if we are to keep `ElementFlag` we should at a minimum provide a better description of its purpose. For example, can/should it be used for all predicates on elements, or just the elements that get "special" handling when generating docs. 2. The use of strings containing HTML, and use of `RawHtml`, instead of working in terms of `Content` nodes such as `HtmlTree` and `StringContent`. 3. Track recent updates to the repo, regarding Conditional Pages. See how we set up conditional pages for the deprecated list, and do the same for preview items. This is probably a must-do item, once you merge with mainline. -- Finally, I realize this is a big chunk of work (well done!), across many areas, and that getting through a review is hard. If it is too hard to address some of the comments here, I'm OK if you file follow-up bugs of at least the same priority and Fix Version as for the main bug here: JDK-8250768. (That applies to #1, #2 above; not #3). src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java line 526: > 524: return (sym.flags() & Flags.PREVIEW_REFLECTIVE) != 0; > 525: } > 526: Generally, hacking your way into `Symbol` is undesirable (though accepted if there is no realistic alternative.) Adding new code into the `WorkArounds` class should be seen as a means of last resort when the required information cannot be obtained from public API ... which may require updating the public API as well. For example, should these methods be predicates on the Language Model `Elements` class? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java line 89: > 87: @Override > 88: protected Content getDeprecatedOrPreviewLink(Element member) { > 89: Content deprecatedLinkContent = new ContentBuilder(); name does not match usage. I suggest simplifying it to just "content". src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java line 88: > 86: > 87: @Override > 88: protected Content getDeprecatedOrPreviewLink(Element member) { This name is a side-effect of the `ElementFlag` question. We should either use explicit field and method names, or we should use `ElementFlag` more consistently. This method name works OK for now, but if if ever gets to have another `orFoo` component in the name, the signature should be parameterized with something like `ElementFlag` or its equivalent. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesIndexWriter.java line 172: > 170: description.add(getDeprecatedPhrase(klass)); > 171: List tags = utils.getDeprecatedTrees(klass); > 172: if (!tags.isEmpty()) { There is potential for future parameterization using `ElementFlag` or its equivalent. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java line 205: > 203: protected Content getDeprecatedOrPreviewLink(Element member) { > 204: String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName(); > 205: return writer.getDocLink(LinkInfoImpl.Kind.MEMBER_DEPRECATED_PREVIEW, member, name); I suspect the MEMBER_DEPRECATED_PREVIEW will become more general in future src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java line 210: > 208: pre.add(modifiersPart); > 209: pre.add(new HtmlTree(TagName.SUP).add(links.createLink(getPreviewSectionAnchor(typeElement), > 210: contents.previewMark))); Possible future enhancement: use a set of modifiers that need flags src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java line 281: > 279: pre.add(DocletConstants.NL); > 280: pre.add("permits"); > 281: pre.add(new HtmlTree(TagName.SUP).add(links.createLink(getPreviewSectionAnchor(typeElement), @hns is it better to use `` or CSS? Either way is OK in this review. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java line 187: > 185: PreviewListWriter.generate(configuration); > 186: } > 187: This may need to be updated, by comparing against similar code for DEPRECATED, and/or you need to take `HtmlDocletWriter.ConditionalPage` into account, again by comparing with latest code for deprecated items. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 112: > 110: import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable; > 111: import jdk.javadoc.internal.doclets.toolkit.util.Utils; > 112: import jdk.javadoc.internal.doclets.toolkit.util.Utils.DeclarationPreviewLanguageFeatures; Uuugh on the long class name ;-) src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1039: > 1037: } else if (utils.isVariableElement(element) || utils.isTypeElement(element)) { > 1038: return getLink(new LinkInfoImpl(configuration, context, typeElement) > 1039: .label(label).where(links.getName(element.getSimpleName().toString())).targetMember(element)); Note to self (@jonathan-gibbons ) links.getName should accept a `CharSequence` to avoid the need for `toString()` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2219: > 2217: if (previewTree != null) { > 2218: div.add(HtmlTree.SPAN(HtmlStyle.previewLabel, > 2219: new RawHtml(utils.getPreviewTreeSummaryOrDetails(previewTree, true)))); There's a big cringe here that there is a method in Utils returning HTML. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2281: > 2279: RawHtml note2 = > 2280: new RawHtml(resources.getText("doclet.PreviewTrailingNote2", > 2281: name)); This is a deviation from existing practice to allow HTML in resource files. That doesn't seem like the sort of stuff that should be localizable. In other situations, (e.g. the Help page) we put the plain-text contents in the resource file and generate the markup in the code. Elsewhere, I said that `WorkArounds` is a means of last resort. The same is true for `RawHtml`. Use it if you must, but it's better to use other forms of `Content`, like `HtmlTree`. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2322: > 2320: feature.features > 2321: .stream() > 2322: .map(f -> "" + f + "") Ugh for using string constants for HTML. Try and use `Content` instead, src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2329: > 2327: featureDisplayName, > 2328: featureCodes); > 2329: result.add(new RawHtml(text)); General ugh for many of the aforementioned reasons, all related to handling HTML in strings. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2351: > 2349: .map(this::toLink) > 2350: .map(link -> getLink(link).toString()) > 2351: .collect(Collectors.joining(", ")))); More of the same ... `RawHtml` and building HTML in strings src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/LinkInfoImpl.java line 64: > 62: * Indicate that the link appears in member documentation on the Deprecated or Preview page. > 63: */ > 64: MEMBER_DEPRECATED_PREVIEW, Will need to be generalized, eventually src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 228: > 226: addTreeLink(tree); > 227: addDeprecatedLink(tree); > 228: addPreviewLink(tree); It's OK to put the link here, I guess, but it should also be on the INDEX page. See also recent updates for conditional pages. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 888: > 886: > 887: private void addPreviewLink(Content tree) { > 888: if (configuration.getIncludedModuleElements().stream().anyMatch(m -> m.getQualifiedName().contentEquals("java.base"))) { This becomes simpler with recent support for conditional pages. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java line 39: > 37: import com.sun.source.doctree.TextTree; > 38: import com.sun.source.doctree.UnknownInlineTagTree; > 39: import java.util.stream.Collectors; why these imports? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 288: > 286: doclet.Declared_Using_Preview.SEALED_PERMITS=Sealed Classes > 287: doclet.PreviewPlatformLeadingNote={0} is a preview API of the Java platform. > 288: doclet.ReflectivePreviewPlatformLeadingNote={0} is a reflective preview API of the Java platform. HTML in resource files is bad. It would be marginally better to move the HTML to the value being substituted (using strings from Content nodes) and even better to use a method that substitutes Content nodes into a resource string (Not sure if that method exists, but it could/should). src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ConstructorWriter.java line 79: > 77: * @param annotationDocTree content tree to which the preview information will be added > 78: */ > 79: void addPreview(ExecutableElement member, Content contentTree); Note to javadoc-team: Consider using default methods to provide an empty implementation. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstructorBuilder.java line 28: > 26: package jdk.javadoc.internal.doclets.toolkit.builders; > 27: > 28: import static java.lang.invoke.ConstantBootstraps.enumConstant; Really? If it is required, it is in the wrong place. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PreviewAPIListBuilder.java line 46: > 44: * deletion without notice. > 45: */ > 46: public class PreviewAPIListBuilder { OK for now, but it might be worth eventually trying to merge this with `DeprecatedListBuilder` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PreviewAPIListBuilder.java line 79: > 77: for (PreviewElementKind kind : PreviewElementKind.values()) { > 78: previewMap.put(kind, > 79: new TreeSet<>(utils.comparators.makeDeprecatedComparator())); The use of `makeDeprecatedComparator` is not awful, but does smell a bit. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PreviewAPIListBuilder.java line 86: > 84: /** > 85: * Build the sorted list of all the deprecated APIs in this run. > 86: * Build separate lists for deprecated modules, packages, classes, constructors, "d-word", twice src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PreviewAPIListBuilder.java line 89: > 87: * methods and fields. > 88: */ > 89: private void buildDeprecatedAPIInfo() { D-word src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PreviewAPIListBuilder.java line 133: > 131: } > 132: } > 133: composeDeprecatedList(previewMap.get(PreviewElementKind.FIELD), I suggest you grep this file for all uses of the d-word src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PreviewAPIListBuilder.java line 158: > 156: * @param members members to be added in the list. > 157: */ > 158: private void composeDeprecatedList(SortedSet sset, List members) { Last time d-word comment. Consider all such uses to be flagged. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2848: > 2846: UnknownInlineTagTree previewTag = (UnknownInlineTagTree) t; > 2847: List previewContent = previewTag.getContent(); > 2848: String previewText = ((TextTree) previewContent.get(0)).getBody(); This looks unreasonably fragile. And, I thought the tag was going away... at least according to earlier files in this review. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2984: > 2982: SEALED(List.of("sealed")), > 2983: SEALED_PERMITS(List.of("sealed", "permits")), > 2984: RECORD(List.of("record")); I'm guessing this is about to go away soon? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2980: > 2978: } > 2979: > 2980: public enum DeclarationPreviewLanguageFeatures { General thinking aloud question ... how does all this interact with source or release options for an earlier release? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3025: > 3023: case MODULE, PACKAGE -> { > 3024: } > 3025: default -> throw new IllegalStateException("Unexpected: " + el.getKind()); Should be `IllegalArgumentException` not `IllegalStateException` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 3145: > 3143: * Checks whether the given Element should be marked as a preview API. > 3144: * > 3145: * Note that is a type is marked as a preview, its members are not. probable typo: "is" -> "if" src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1288: > 1286: case FIELD: case INSTANCE_INIT: case LOCAL_VARIABLE: case PARAMETER: > 1287: case RESOURCE_VARIABLE: case STATIC_INIT: case TYPE_PARAMETER: > 1288: case RECORD_COMPONENT: I'm not saying this is wrong, but I'd like to understand why it is necessary. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From ihse at openjdk.java.net Mon Oct 26 09:56:16 2020 From: ihse at openjdk.java.net (Magnus Ihse Bursie) Date: Mon, 26 Oct 2020 09:56:16 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: References: Message-ID: On Fri, 23 Oct 2020 16:21:53 GMT, 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 incrementally with one additional commit since the last revision: > > Removing unnecessary cast. Build changes look good. ------------- Marked as reviewed by ihse (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Tue Oct 27 16:14:33 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Tue, 27 Oct 2020 16:14:33 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: References: Message-ID: <281-fNSKFfd-qngLAcLkMFdmKe-XHD-0qKCEh4OGvog=.82b534a0-e57a-41bf-ba94-e487601b2773@github.com> On Fri, 23 Oct 2020 17:22:33 GMT, Jonathan Gibbons wrote: >> Jan Lahoda has updated the pull request incrementally with one additional commit since the last revision: >> >> Removing unnecessary cast. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java line 88: > >> 86: >> 87: @Override >> 88: protected Content getDeprecatedOrPreviewLink(Element member) { > > This name is a side-effect of the `ElementFlag` question. We should either use explicit field and method names, or we should use `ElementFlag` more consistently. This method name works OK for now, but if if ever gets to have another `orFoo` component in the name, the signature should be parameterized with something like `ElementFlag` or its equivalent. Note this method returns the same link for deprecate or preview - it just was named "getDeprecatedLink", and when using it work preview, I renamed it "getDeprecatedOrPreviewLink". We may need to think of a better name. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2980: > >> 2978: } >> 2979: >> 2980: public enum DeclarationPreviewLanguageFeatures { > > General thinking aloud question ... how does all this interact with source or release options for an earlier release? I don't think there should be much interaction with -source . We don't support preview features from previous version or preview class files from previous versions, so I think it should be enough to handle the currently present preview features. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2984: > >> 2982: SEALED(List.of("sealed")), >> 2983: SEALED_PERMITS(List.of("sealed", "permits")), >> 2984: RECORD(List.of("record")); > > I'm guessing this is about to go away soon? Right, this is likely to go away soon. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Thu Oct 29 09:28:51 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Thu, 29 Oct 2020 09:28:51 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: References: Message-ID: On Fri, 23 Oct 2020 18:28:12 GMT, Jonathan Gibbons wrote: >> Jan Lahoda has updated the pull request incrementally with one additional commit since the last revision: >> >> Removing unnecessary cast. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1288: > >> 1286: case FIELD: case INSTANCE_INIT: case LOCAL_VARIABLE: case PARAMETER: >> 1287: case RESOURCE_VARIABLE: case STATIC_INIT: case TYPE_PARAMETER: >> 1288: case RECORD_COMPONENT: > > I'm not saying this is wrong, but I'd like to understand why it is necessary. HtmlDocletWriter.getPreviewNotes analyzes classes and their members, to see if some are using aspects that are under preview. When looking at the members, it uses utils.isIncluded on the member, and that eventually gets here. And if the member is a RECORD_COMPONENT, it would fail here. But we can avoid asking for RECORD_COMPONENTS, if needed. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Thu Oct 29 09:41:50 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Thu, 29 Oct 2020 09:41:50 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: References: Message-ID: On Fri, 23 Oct 2020 17:58:42 GMT, Jonathan Gibbons wrote: >> Jan Lahoda has updated the pull request incrementally with one additional commit since the last revision: >> >> Removing unnecessary cast. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 228: > >> 226: addTreeLink(tree); >> 227: addDeprecatedLink(tree); >> 228: addPreviewLink(tree); > > It's OK to put the link here, I guess, but it should also be on the INDEX page. > > See also recent updates for conditional pages. I believe the link is in the navigation bar on all pages (as DEPRECATED is). ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Thu Oct 29 09:46:46 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Thu, 29 Oct 2020 09:46:46 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: References: Message-ID: <3izxrckqtdi9Hg7tV7-EUeIV0M7oqmMl3j802UTtFuM=.014127ae-6ca1-4309-91b7-a622e5fe89c4@github.com> On Fri, 23 Oct 2020 18:19:13 GMT, Jonathan Gibbons wrote: >> Jan Lahoda has updated the pull request incrementally with one additional commit since the last revision: >> >> Removing unnecessary cast. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2848: > >> 2846: UnknownInlineTagTree previewTag = (UnknownInlineTagTree) t; >> 2847: List previewContent = previewTag.getContent(); >> 2848: String previewText = ((TextTree) previewContent.get(0)).getBody(); > > This looks unreasonably fragile. And, I thought the tag was going away... at least according to earlier files in this review. This was intended to allow Preview APIs to provide their own text instead of the generic one. But, looking again at JEP 12, this shouldn't be supported, so removing. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Thu Oct 29 09:46:47 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Thu, 29 Oct 2020 09:46:47 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v4] In-Reply-To: <281-fNSKFfd-qngLAcLkMFdmKe-XHD-0qKCEh4OGvog=.82b534a0-e57a-41bf-ba94-e487601b2773@github.com> References: <281-fNSKFfd-qngLAcLkMFdmKe-XHD-0qKCEh4OGvog=.82b534a0-e57a-41bf-ba94-e487601b2773@github.com> Message-ID: On Tue, 27 Oct 2020 16:11:18 GMT, Jan Lahoda wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 2980: >> >>> 2978: } >>> 2979: >>> 2980: public enum DeclarationPreviewLanguageFeatures { >> >> General thinking aloud question ... how does all this interact with source or release options for an earlier release? > > I don't think there should be much interaction with -source . We don't support preview features from previous version or preview class files from previous versions, so I think it should be enough to handle the currently present preview features. We don't support preview features from previous releases, AFAIK. So javadoc for JDK 16 should not accept e.g. record class when running with -source 15. ------------- PR: https://git.openjdk.java.net/jdk/pull/703 From jlahoda at openjdk.java.net Fri Oct 30 08:30:58 2020 From: jlahoda at openjdk.java.net (Jan Lahoda) Date: Fri, 30 Oct 2020 08:30:58 GMT Subject: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v5] In-Reply-To: References: Message-ID: > 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 44 commits: - 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. - Reflecting review comments. - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into JDK-8250768 - ... and 34 more: https://git.openjdk.java.net/jdk/compare/ea26ff11...d76eb293 ------------- Changes: https://git.openjdk.java.net/jdk/pull/703/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=04 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