From aturbanov at openjdk.org Mon Aug 1 07:01:15 2022 From: aturbanov at openjdk.org (Andrey Turbanov) Date: Mon, 1 Aug 2022 07:01:15 GMT Subject: RFR: 8289658: Avoid redundant LinkedHashMap.get call in TagletManager.addNewSimpleCustomTag [v4] In-Reply-To: References: Message-ID: <3nd9uNRqSEEzBEz0_KowRIn9zqaXNRQetzWP6ANQ5dY=.2e235c00-d64d-4653-8c89-b75064929c7e@github.com> > Instead of pair `LinkedHashMap.get`+`LinkedHashMap.remove` calls, we can use value returned from single `allTaglets.remove` call. > It's shorter and a bit faster. > https://github.com/openjdk/jdk/blob/d46f404b3179c66e8e5775a9e2253c95238153c7/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java#L314-L325 Andrey Turbanov has updated the pull request incrementally with one additional commit since the last revision: 8289658: Avoid redundant LinkedHashMap.get call in TagletManager.addNewSimpleCustomTag improve comment ------------- Changes: - all: https://git.openjdk.org/jdk/pull/9137/files - new: https://git.openjdk.org/jdk/pull/9137/files/9c580c5a..f4262e58 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=9137&range=03 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=9137&range=02-03 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/9137.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9137/head:pull/9137 PR: https://git.openjdk.org/jdk/pull/9137 From duke at openjdk.org Mon Aug 1 12:47:44 2022 From: duke at openjdk.org (Joe) Date: Mon, 1 Aug 2022 12:47:44 GMT Subject: RFR: 8289562: Change bugs.java.com and bugreport.java.com URL's to https Message-ID: 8289562: Change bugs.java.com and bugreport.java.com URL's to https ------------- Commit messages: - Merge branch 'openjdk:master' into master - changed the hrl from http to https JDK-8289562 Changes: https://git.openjdk.org/jdk/pull/9445/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=9445&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8289562 Stats: 18 lines in 17 files changed: 0 ins; 0 del; 18 mod Patch: https://git.openjdk.org/jdk/pull/9445.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9445/head:pull/9445 PR: https://git.openjdk.org/jdk/pull/9445 From fmatte at openjdk.org Mon Aug 1 14:32:47 2022 From: fmatte at openjdk.org (Fairoz Matte) Date: Mon, 1 Aug 2022 14:32:47 GMT Subject: RFR: 8289562: Change bugs.java.com and bugreport.java.com URL's to https In-Reply-To: References: Message-ID: On Mon, 11 Jul 2022 08:04:20 GMT, Joe wrote: > 8289562: Change bugs.java.com and bugreport.java.com URL's to https It is a trivial change and looks good to me (I am not a reviewer). ------------- PR: https://git.openjdk.org/jdk/pull/9445 From naoto at openjdk.org Mon Aug 1 16:46:01 2022 From: naoto at openjdk.org (Naoto Sato) Date: Mon, 1 Aug 2022 16:46:01 GMT Subject: [jdk19] RFR: 8290889: JDK 19 RDP2 L10n resource files update - msgdrop 10 [v4] In-Reply-To: References: Message-ID: On Fri, 29 Jul 2022 18:13:25 GMT, Alisen Chung wrote: >> open l10n msg drop >> All tests passed. > > Alisen Chung has updated the pull request incrementally with one additional commit since the last revision: > > added comments in CurrencyNames root in base, moved US CurrencyNames back to base, readded original Chinese translation LGTM ------------- Marked as reviewed by naoto (Reviewer). PR: https://git.openjdk.org/jdk19/pull/154 From prr at openjdk.org Mon Aug 1 22:52:52 2022 From: prr at openjdk.org (Phil Race) Date: Mon, 1 Aug 2022 22:52:52 GMT Subject: RFR: 8289562: Change bugs.java.com and bugreport.java.com URL's to https In-Reply-To: References: Message-ID: On Mon, 11 Jul 2022 08:04:20 GMT, Joe wrote: > 8289562: Change bugs.java.com and bugreport.java.com URL's to https Looks fine to me. However the langtools / javadoc folks seem like they should be primary reviewers since it is mostly messages from the tools. ------------- Marked as reviewed by prr (Reviewer). PR: https://git.openjdk.org/jdk/pull/9445 From duke at openjdk.org Sat Aug 6 09:05:12 2022 From: duke at openjdk.org (Patrick Pfeifer) Date: Sat, 6 Aug 2022 09:05:12 GMT Subject: [jdk19] RFR: 8278274: Update nroff pages in JDK 19 before RC In-Reply-To: <75mqpwhSuTfYsLguWkG0izRelatkAX7wOwsjC3crYFI=.2449d017-855e-4da9-b1b3-2fcee65cba2c@github.com> References: <75mqpwhSuTfYsLguWkG0izRelatkAX7wOwsjC3crYFI=.2449d017-855e-4da9-b1b3-2fcee65cba2c@github.com> Message-ID: On Mon, 18 Jul 2022 15:22:01 GMT, Jonathan Gibbons wrote: >> Please review these changes to the nroff manpage files so that they match their markdown sources that Oracle maintains. >> >> All pages at a minimum have 19-ea replaced with 19, and copyright set to 2022 if needed. Additionally: >> >> The Java manpage was missing updates from: >> - [JDK-8282018](https://bugs.openjdk.org/browse/JDK-8282018): Add captions to tables on java man page. >> >> The Java manpage has slight formatting differences from: >> - [JDK-8262004](https://bugs.openjdk.org/browse/JDK-8262004): Classpath separator: Man page says semicolon; should be colon on Linux >> - [JDK-8236569](https://bugs.openjdk.org/browse/JDK-8236569): -Xss not multiple of 4K does not work for the main thread on macOS >> >> The Java manpage has a typo fixed in mainline by [JDK-8279047](https://bugs.openjdk.org/browse/JDK-8279047) (for JDK 20) >> >> >> The keytool manpage was missing updates from: >> - [JDK-8282014](https://bugs.openjdk.org/browse/JDK-8282014): Add captions to tables on keytool man page. >> - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger default key sizes and algorithms based on CNSA >> >> The jar manpage was missing updates from: >> - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod man pages need the new --date documenting from CSR [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755) >> >> The jarsigner manpage was missing updates from: >> - [JDK-8282015](https://bugs.openjdk.org/browse/JDK-8282015): Add captions to tables on jarsigner man page. >> - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger default key sizes and algorithms based on CNSA >> >> The javadoc manpage was missing updates from: >> - [JDK-8279034](https://bugs.openjdk.org/browse/JDK-8279034): Update man page for javadoc `--date` option >> >> The jmod manpage was missing updates from: >> - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod man pages need the new --date documenting from CSR [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755) >> >> The jpackage manpage was missing updates from: >> - [JDK-8285146](https://bugs.openjdk.org/browse/JDK-8285146): Document jpackage resource dir feature >> - [JDK-8284695](https://bugs.openjdk.org/browse/JDK-8284695): Update jpackage man pages for JDK 19 >> - [JDK-8284209](https://bugs.openjdk.org/browse/JDK-8284209): Replace remaining usages of 'a the' in source code >> >> The jshell manpage was missing updates from: >> - [JDK-8282016](https://bugs.openjdk.org/browse/JDK-8282016): Add captions to tables on jshell man page. > > src/java.base/share/man/keytool.1 line 456: > >> 454: \f[CB]PrivateKeyEntry\f[R] for the signer that already exists in the >> 455: keystore. >> 456: This option is used to sign the certificate with the signer?s private > > Not a problem with this PR as such, but we still have a `?` character in the output. Hello @jonathan-gibbons Excuse my hijacking / piggy-backing on this conversation! When you say > Not a problem with this PR as such, but we still have a `?` character in the output. This strongly suggests that there must be an input to those man pages somewhere. :-) Would you mind to point me to it? Are they even included in the git repo? Also, I was wondering why these man pages (i.e. the outputs) are obviously not included any more in the OpenJDK builds, e.g. https://jdk.java.net/19/ ? I am not sure when they were removed or if they were ever included in _open_jdk builds at all, but I see them in the Oracle JDK 1.8 Build. I find them really nice to read! Are there other output formats, e.g. HTML, that might be are deployed somewhere on the web? ------------- PR: https://git.openjdk.org/jdk19/pull/145 From duke at openjdk.org Sat Aug 6 13:54:20 2022 From: duke at openjdk.org (Patrick Pfeifer) Date: Sat, 6 Aug 2022 13:54:20 GMT Subject: [jdk19] RFR: 8278274: Update nroff pages in JDK 19 before RC In-Reply-To: References: <75mqpwhSuTfYsLguWkG0izRelatkAX7wOwsjC3crYFI=.2449d017-855e-4da9-b1b3-2fcee65cba2c@github.com> Message-ID: <_53Ro95x3TDbVcRUoOr4L0HiWCyepU8CgcyPCwLwKLA=.6ce49e6c-9b4b-4c8e-b0b8-7ec76b0f3d85@github.com> On Sat, 6 Aug 2022 09:01:39 GMT, Patrick Pfeifer wrote: >> src/java.base/share/man/keytool.1 line 456: >> >>> 454: \f[CB]PrivateKeyEntry\f[R] for the signer that already exists in the >>> 455: keystore. >>> 456: This option is used to sign the certificate with the signer?s private >> >> Not a problem with this PR as such, but we still have a `?` character in the output. > > Hello @jonathan-gibbons > > Excuse my hijacking / piggy-backing on this conversation! > > When you say > >> Not a problem with this PR as such, but we still have a `?` character in the output. > > This strongly suggests that there must be an input to those man pages somewhere. :-) Would you mind to point me to it? Are they even included in the git repo? > > Also, I was wondering why these man pages (i.e. the outputs) are obviously not included any more in the OpenJDK builds, e.g. https://jdk.java.net/19/ ? I am not sure when they were removed or if they were ever included in _open_jdk builds at all, but I see them in the Oracle JDK 1.8 Build. > > I find them really nice to read! Are there other output formats, e.g. HTML, that might be are deployed somewhere on the web? It did not take much effort to answer the last of the above question myself. > Are there other output formats, e.g. HTML, that might be are deployed somewhere on the web? Obviously "yes". HTML renderings can be found by following the, e.g. "[Java Development Kit Version 18 Tool Specifications](https://docs.oracle.com/en/java/javase/18/docs/specs/man/index.html)" Link on the "Specifications Overview" page at, e.g. "https://docs.oracle.com/en/java/javase/18/docs/specs/". Still hunting for the sources. ------------- PR: https://git.openjdk.org/jdk19/pull/145 From david.holmes at oracle.com Sun Aug 7 23:59:08 2022 From: david.holmes at oracle.com (David Holmes) Date: Mon, 8 Aug 2022 09:59:08 +1000 Subject: [jdk19] RFR: 8278274: Update nroff pages in JDK 19 before RC In-Reply-To: References: <75mqpwhSuTfYsLguWkG0izRelatkAX7wOwsjC3crYFI=.2449d017-855e-4da9-b1b3-2fcee65cba2c@github.com> Message-ID: <161d24ca-ff52-b2fe-0874-461e98900e28@oracle.com> Hi Patrick, On 6/08/2022 7:05 pm, Patrick Pfeifer wrote: > On Mon, 18 Jul 2022 15:22:01 GMT, Jonathan Gibbons wrote: > >>> Please review these changes to the nroff manpage files so that they match their markdown sources that Oracle maintains. >> >> Not a problem with this PR as such, but we still have a `?` character in the output. > > Hello @jonathan-gibbons > > Excuse my hijacking / piggy-backing on this conversation! > > When you say > >> Not a problem with this PR as such, but we still have a `?` character in the output. > > This strongly suggests that there must be an input to those man pages somewhere. :-) Would you mind to point me to it? Are they even included in the git repo? The sources to the manpages are not currently open sourced and so are held in Oracle's internal repository. Making them open-sourced has been a goal for some time now but has to overcome legal obstacles, but we are hopeful it will be "soon". > Also, I was wondering why these man pages (i.e. the outputs) are obviously not included any more in the OpenJDK builds, e.g. https://jdk.java.net/19/ ? I am not sure when they were removed or if they were ever included in _open_jdk builds at all, but I see them in the Oracle JDK 1.8 Build. > > I find them really nice to read! Are there other output formats, e.g. HTML, that might be are deployed somewhere on the web? As you found, Oracle does provide these in html format. Cheers, David > ------------- > > PR: https://git.openjdk.org/jdk19/pull/145 From hannesw at openjdk.org Mon Aug 8 10:25:18 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Mon, 8 Aug 2022 10:25:18 GMT Subject: RFR: JDK-8236048: Cleanup use of Utils.normalizeNewlines In-Reply-To: References: Message-ID: On Sat, 30 Jul 2022 00:36:06 GMT, Jonathan Gibbons wrote: > Please review a medium-size cleanup related to handling newlines in `Content`/`HtmlTree`/`Text[Builder]` trees. > This is the 3rd and last in the recent series of cleanup tasks in the code to generate HTML. > > Until recently, the `Text`/`TextBuilder` objects were "ready-for-writing", meaning that characters like `<`, `&`, etc were encoded as entities, and newlines were represented by the platform line separator. This caused difficulties when counting the size of generated text, since these characters had to be detected and accounted for. A recent change addressed entities, but stayed clear of the newline issue, which is now addressed here. > > A related performance problem is that the method `Utils.normalizeNewlines` always created new strings, even when it was not necessary. > > With this change, newlines in `Text`, `TextBuilder` and other subtypes of `Content` containing text are always represented by `\n`, and are converted to the platform line separator as needed. > > I note the following assumptions: > > * the input may contain any flavor of newlines in the user-provided documentation comments > * the output should aways use the platform line separator (`\n` on Linux and macOS, `\r\n` on Windows etc.) > > Together, these imply that some amount of the input will need to be scanned to normalize newlines at some point in the process. While it would be nice to not have to normalize newlines, it's a case or "pay now, or pay later". > > Notable parts of this change: > > * `Utils.normalizeNewlines` is moved to be a static method in `Text` and rewritten to not create new strings unless needed. This allows a number of questionable imports of `toolkit.utils.DocletConstants` to be removed from the `html.markup` package. While it would be possible to call this method automatically on all strings passed to `Text`, `TextBuilder` etc, in many cases it is not necessary: put another way, it only needs to be called on strings that have come from the user, either in documentation comments or in command-line options. > * `Content.write`, and the implementations thereof, are given a new parameter which gives the newline sequence to use. This is set to `\n` for `toString` and the platform separator when writing to a file. > * `DocletConstants.NL` goes away and is superseded by: > * `Text.NL`: always `\n`, to be used when adding text to a `Content` tree (this replaces most uses of `DocletConstants.NL`) > * `DocFile.PLATFORM_LINE_SEPARATOR`: the platform line separator, to be used when writing to files > * The various `charCount` methods no longer have to worry about use of the platform line separator > * Assertions are used to verify that there are no `\r` characters added into `Text`/`TextBuilder`/`RawHtml`/`Content` > > Other cleanup: > * `DocletConstants.DEFAULT_TAB_STOP_LENGTH` is moved to `BaseOptions` which is the only class that uses it. This leaves just two remaining constants in `DocletConstants` which should probably be moved elsewhere as well, and the `DocletConstants` class deleted. That is a step too far for the work here. > * Minor IDE-suggestions, for lambdas, enhanced switch, adding braces, etc > > One test was affected by the `DocletConstants.NL` change, but apart from that, this is a pure-cleanup change, with no (intentional) externally visible effect. This looks quite good. Apart from the inline comments, I wondered about the following: - Would the methods and constant you moved to `Text` be better placed in `Content` as they are used in other Content instances? - There are quite a few uses of the `"\n"` string literal in a content or pre-content context where the `NL` constant couuld be used. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java line 80: > 78: writer.write(docType.text); > 79: writer.write(newline); > 80: docContent.write(writer, newline,true); Missing space after comma src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java line 161: > 159: } > 160: count++; > 161: break; The RawHtml constructor contains `assert Text.checkNewlines(rawHtml)` so I'm not sure this is actually needed. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Text.java line 51: > 49: */ > 50: public static Text of(CharSequence content) { > 51: assert checkNewlines(content); Redundant assert as private constructor also contains it. ------------- PR: https://git.openjdk.org/jdk/pull/9691 From asemenyuk at openjdk.org Tue Aug 9 17:53:36 2022 From: asemenyuk at openjdk.org (Alexey Semenyuk) Date: Tue, 9 Aug 2022 17:53:36 GMT Subject: [jdk19] RFR: 8290889: JDK 19 RDP2 L10n resource files update - msgdrop 10 [v4] In-Reply-To: References: Message-ID: On Fri, 29 Jul 2022 18:13:25 GMT, Alisen Chung wrote: >> open l10n msg drop >> All tests passed. > > Alisen Chung has updated the pull request incrementally with one additional commit since the last revision: > > added comments in CurrencyNames root in base, moved US CurrencyNames back to base, readded original Chinese translation Marked as reviewed by asemenyuk (Reviewer). jpackage changes look good. Approved that part. ------------- PR: https://git.openjdk.org/jdk19/pull/154 From achung at openjdk.org Tue Aug 9 22:30:54 2022 From: achung at openjdk.org (Alisen Chung) Date: Tue, 9 Aug 2022 22:30:54 GMT Subject: [jdk19] Integrated: 8290889: JDK 19 RDP2 L10n resource files update - msgdrop 10 In-Reply-To: References: Message-ID: On Sat, 23 Jul 2022 03:03:25 GMT, Alisen Chung wrote: > open l10n msg drop > All tests passed. This pull request has now been integrated. Changeset: 0def5316 Author: Alisen Chung Committer: Alexey Semenyuk URL: https://git.openjdk.org/jdk19/commit/0def5316cd2ec7699c649bf67bf58e6315c3010b Stats: 684 lines in 42 files changed: 87 ins; 540 del; 57 mod 8290889: JDK 19 RDP2 L10n resource files update - msgdrop 10 Reviewed-by: naoto, asemenyuk ------------- PR: https://git.openjdk.org/jdk19/pull/154 From dholmes at openjdk.org Thu Aug 11 05:26:56 2022 From: dholmes at openjdk.org (David Holmes) Date: Thu, 11 Aug 2022 05:26:56 GMT Subject: Integrated: Merge jdk19 Message-ID: Forward port JDK 19 -> JDK 20 ------------- Commit messages: - Merge remote-tracking branch 'jdk19/master' into Merge_jdk19 - 8288769: Revert unintentional change to deflate.c - 8291496: Allocating card table before heap causes underflow asserts in CardTable::addr_for() - 8290889: JDK 19 RDP2 L10n resource files update - msgdrop 10 The webrevs contain the adjustments done while merging with regards to each parent branch: - master: https://webrevs.openjdk.org/?repo=jdk&pr=9828&range=00.0 - jdk19: https://webrevs.openjdk.org/?repo=jdk&pr=9828&range=00.1 Changes: https://git.openjdk.org/jdk/pull/9828/files Stats: 686 lines in 44 files changed: 89 ins; 540 del; 57 mod Patch: https://git.openjdk.org/jdk/pull/9828.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9828/head:pull/9828 PR: https://git.openjdk.org/jdk/pull/9828 From dholmes at openjdk.org Thu Aug 11 05:26:56 2022 From: dholmes at openjdk.org (David Holmes) Date: Thu, 11 Aug 2022 05:26:56 GMT Subject: Integrated: Merge jdk19 In-Reply-To: References: Message-ID: On Thu, 11 Aug 2022 00:06:35 GMT, David Holmes wrote: > Forward port JDK 19 -> JDK 20 This pull request has now been integrated. Changeset: 85a60235 Author: David Holmes URL: https://git.openjdk.org/jdk/commit/85a602355ff6e92bb468135d712e0b0b41753db4 Stats: 686 lines in 44 files changed: 89 ins; 540 del; 57 mod Merge ------------- PR: https://git.openjdk.org/jdk/pull/9828 From hannesw at openjdk.org Thu Aug 11 15:36:20 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 11 Aug 2022 15:36:20 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors Message-ID: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ - Some colors have been unified to reduce the number of variable definitions: - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) - Header cells of user defined tables now use the same color as structural tables - Some sub-pixel sizing and spacing changes in random places Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. ------------- Commit messages: - JDK-8289334: Use CSS variables to define fonts and colors Changes: https://git.openjdk.org/jdk/pull/9839/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=9839&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8289334 Stats: 245 lines in 11 files changed: 51 ins; 48 del; 146 mod Patch: https://git.openjdk.org/jdk/pull/9839.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9839/head:pull/9839 PR: https://git.openjdk.org/jdk/pull/9839 From jjg at openjdk.org Tue Aug 16 17:37:29 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 17:37:29 GMT Subject: RFR: 8289562: Change bugs.java.com and bugreport.java.com URL's to https In-Reply-To: References: Message-ID: On Mon, 11 Jul 2022 08:04:20 GMT, Joe wrote: > 8289562: Change bugs.java.com and bugreport.java.com URL's to https `jdk.compiler` and `jdk.javadoc` changes look OK ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.org/jdk/pull/9445 From naoto at openjdk.org Tue Aug 16 17:48:39 2022 From: naoto at openjdk.org (Naoto Sato) Date: Tue, 16 Aug 2022 17:48:39 GMT Subject: RFR: 8289562: Change bugs.java.com and bugreport.java.com URL's to https In-Reply-To: References: Message-ID: On Mon, 11 Jul 2022 08:04:20 GMT, Joe wrote: > 8289562: Change bugs.java.com and bugreport.java.com URL's to https Those `.properties` bundle changes look good. ------------- Marked as reviewed by naoto (Reviewer). PR: https://git.openjdk.org/jdk/pull/9445 From iris at openjdk.org Tue Aug 16 18:26:17 2022 From: iris at openjdk.org (Iris Clark) Date: Tue, 16 Aug 2022 18:26:17 GMT Subject: RFR: 8289562: Change bugs.java.com and bugreport.java.com URL's to https In-Reply-To: References: Message-ID: On Mon, 11 Jul 2022 08:04:20 GMT, Joe wrote: > 8289562: Change bugs.java.com and bugreport.java.com URL's to https Marked as reviewed by iris (Reviewer). ------------- PR: https://git.openjdk.org/jdk/pull/9445 From jjg at openjdk.org Tue Aug 16 19:54:25 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 19:54:25 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Thu, 11 Aug 2022 15:29:46 GMT, Hannes Walln?fer wrote: > Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. > > [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: > > [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ > > - Some colors have been unified to reduce the number of variable definitions: > - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) > - Header cells of user defined tables now use the same color as structural tables > - Some sub-pixel sizing and spacing changes in random places > > Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette > > The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. Mostly excellent. There is one question about why you have converted some values from hex to `rgba` values, not to CSS custom properties. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java line 333: > 331: // The order of the addStylesheet(...) calls is important > 332: addStylesheet(head, DocPaths.SCRIPT_DIR.resolve(DocPaths.JQUERY_UI_CSS)); > 333: addStylesheet(head, DocPaths.JQUERY_OVERRIDES_CSS); The edit as-is is OK, but the general code here makes me wonder if this class belongs in the `markup` package. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 89: > 87: } > 88: h1 { > 89: font-size:1.428em; I appreciate these numbers give per-pixel consistency with before, but 3 decimal places seems a bit extreme! src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 959: > 957: } > 958: div.page-search-info button#page-search-copy:hover { > 959: background-color: rgba(128, 128, 160, 0.2); why have the old hex values just been converted to `rgba` values, and not CSS custom properties? ------------- PR: https://git.openjdk.org/jdk/pull/9839 From jjg at openjdk.org Tue Aug 16 20:09:38 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 20:09:38 GMT Subject: RFR: JDK-8289332: Auto-generate ids for user-defined headings In-Reply-To: References: Message-ID: On Mon, 25 Jul 2022 15:10:36 GMT, Hannes Walln?fer wrote: > This is a simple change to automatically generate `id` attributes for HTML headers in documentation comments. > > I decided to leave the functionality in `HtmlDocletWriter` rather than moving it to `HtmlIds` because it uses the same helper methods as`commentTagsToContent`. > > The value of the `id` attribute id derived from the content of the header tag with spaces and other non-word characters replaced by `-`. A `-hdr` suffix is appended to avoid collisions with other ids. If there are duplicate values an int counter is appended to make them unique. Some inline comments/questions. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1762: > 1760: private boolean hasIdAttribute(StartElementTree node) { > 1761: return node.getAttributes().stream().anyMatch( > 1762: dt -> equalsIgnoreCase(((AttributeTree)dt).getName(), "id")); Do you need to filter/map the stream to ensure no class cast exceptions? Can the attributes include `ErroneousTree`? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1791: > 1789: if (!idValue.isEmpty()) { > 1790: // Make id unique > 1791: idValue = idValue + "-hdr"; Would it be better to use `header` rather than just `hdr` ? Better still, `heading` seems to be the term in the HTML spec; `header` is also used, but not for headings. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1800: > 1798: } > 1799: content.add("id=\"").add(idValue).add("\""); > 1800: } This part of the algorithm, to create an `id` from the text contents of a header, still feels like it belongs in `HtmlIds`. It feels like we should have HtmlIds.getIdForHeader(CharSequence headerText) or something like that ------------- PR: https://git.openjdk.org/jdk/pull/9627 From jjg at openjdk.org Tue Aug 16 20:14:18 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 20:14:18 GMT Subject: RFR: JDK-8273860: Javadoc Deprecated API list should not use italic font for description column In-Reply-To: References: Message-ID: On Tue, 5 Jul 2022 11:01:46 GMT, Hannes Walln?fer wrote: > Please review a trivial change to use plain font for deprecation comments in the Deprecated API page. Italic font is used to make deprecation comments stand out against other parts of the documentation, but here the content consists exclusively of deprecation comments so the same so the font style should be the same as in other API summary pages. Marked as reviewed by jjg (Reviewer). ------------- PR: https://git.openjdk.org/jdk/pull/9375 From jjg at openjdk.org Tue Aug 16 21:32:34 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 21:32:34 GMT Subject: RFR: JDK-8236048: Cleanup use of Utils.normalizeNewlines In-Reply-To: References: Message-ID: On Mon, 8 Aug 2022 10:03:05 GMT, Hannes Walln?fer wrote: >> Please review a medium-size cleanup related to handling newlines in `Content`/`HtmlTree`/`Text[Builder]` trees. >> This is the 3rd and last in the recent series of cleanup tasks in the code to generate HTML. >> >> Until recently, the `Text`/`TextBuilder` objects were "ready-for-writing", meaning that characters like `<`, `&`, etc were encoded as entities, and newlines were represented by the platform line separator. This caused difficulties when counting the size of generated text, since these characters had to be detected and accounted for. A recent change addressed entities, but stayed clear of the newline issue, which is now addressed here. >> >> A related performance problem is that the method `Utils.normalizeNewlines` always created new strings, even when it was not necessary. >> >> With this change, newlines in `Text`, `TextBuilder` and other subtypes of `Content` containing text are always represented by `\n`, and are converted to the platform line separator as needed. >> >> I note the following assumptions: >> >> * the input may contain any flavor of newlines in the user-provided documentation comments >> * the output should aways use the platform line separator (`\n` on Linux and macOS, `\r\n` on Windows etc.) >> >> Together, these imply that some amount of the input will need to be scanned to normalize newlines at some point in the process. While it would be nice to not have to normalize newlines, it's a case or "pay now, or pay later". >> >> Notable parts of this change: >> >> * `Utils.normalizeNewlines` is moved to be a static method in `Text` and rewritten to not create new strings unless needed. This allows a number of questionable imports of `toolkit.utils.DocletConstants` to be removed from the `html.markup` package. While it would be possible to call this method automatically on all strings passed to `Text`, `TextBuilder` etc, in many cases it is not necessary: put another way, it only needs to be called on strings that have come from the user, either in documentation comments or in command-line options. >> * `Content.write`, and the implementations thereof, are given a new parameter which gives the newline sequence to use. This is set to `\n` for `toString` and the platform separator when writing to a file. >> * `DocletConstants.NL` goes away and is superseded by: >> * `Text.NL`: always `\n`, to be used when adding text to a `Content` tree (this replaces most uses of `DocletConstants.NL`) >> * `DocFile.PLATFORM_LINE_SEPARATOR`: the platform line separator, to be used when writing to files >> * The various `charCount` methods no longer have to worry about use of the platform line separator >> * Assertions are used to verify that there are no `\r` characters added into `Text`/`TextBuilder`/`RawHtml`/`Content` >> >> Other cleanup: >> * `DocletConstants.DEFAULT_TAB_STOP_LENGTH` is moved to `BaseOptions` which is the only class that uses it. This leaves just two remaining constants in `DocletConstants` which should probably be moved elsewhere as well, and the `DocletConstants` class deleted. That is a step too far for the work here. >> * Minor IDE-suggestions, for lambdas, enhanced switch, adding braces, etc >> >> One test was affected by the `DocletConstants.NL` change, but apart from that, this is a pure-cleanup change, with no (intentional) externally visible effect. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java line 80: > >> 78: writer.write(docType.text); >> 79: writer.write(newline); >> 80: docContent.write(writer, newline,true); > > Missing space after comma Fixed. This is a mildly annoying side-effect of IDEA wanting to label boolean arguments: it makes the missing spaces much harder to see. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Text.java line 51: > >> 49: */ >> 50: public static Text of(CharSequence content) { >> 51: assert checkNewlines(content); > > Redundant assert as private constructor also contains it. Fixed ------------- PR: https://git.openjdk.org/jdk/pull/9691 From jjg at openjdk.org Tue Aug 16 21:39:16 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 21:39:16 GMT Subject: RFR: JDK-8236048: Cleanup use of Utils.normalizeNewlines In-Reply-To: References: Message-ID: On Mon, 8 Aug 2022 10:15:41 GMT, Hannes Walln?fer wrote: >> Please review a medium-size cleanup related to handling newlines in `Content`/`HtmlTree`/`Text[Builder]` trees. >> This is the 3rd and last in the recent series of cleanup tasks in the code to generate HTML. >> >> Until recently, the `Text`/`TextBuilder` objects were "ready-for-writing", meaning that characters like `<`, `&`, etc were encoded as entities, and newlines were represented by the platform line separator. This caused difficulties when counting the size of generated text, since these characters had to be detected and accounted for. A recent change addressed entities, but stayed clear of the newline issue, which is now addressed here. >> >> A related performance problem is that the method `Utils.normalizeNewlines` always created new strings, even when it was not necessary. >> >> With this change, newlines in `Text`, `TextBuilder` and other subtypes of `Content` containing text are always represented by `\n`, and are converted to the platform line separator as needed. >> >> I note the following assumptions: >> >> * the input may contain any flavor of newlines in the user-provided documentation comments >> * the output should aways use the platform line separator (`\n` on Linux and macOS, `\r\n` on Windows etc.) >> >> Together, these imply that some amount of the input will need to be scanned to normalize newlines at some point in the process. While it would be nice to not have to normalize newlines, it's a case or "pay now, or pay later". >> >> Notable parts of this change: >> >> * `Utils.normalizeNewlines` is moved to be a static method in `Text` and rewritten to not create new strings unless needed. This allows a number of questionable imports of `toolkit.utils.DocletConstants` to be removed from the `html.markup` package. While it would be possible to call this method automatically on all strings passed to `Text`, `TextBuilder` etc, in many cases it is not necessary: put another way, it only needs to be called on strings that have come from the user, either in documentation comments or in command-line options. >> * `Content.write`, and the implementations thereof, are given a new parameter which gives the newline sequence to use. This is set to `\n` for `toString` and the platform separator when writing to a file. >> * `DocletConstants.NL` goes away and is superseded by: >> * `Text.NL`: always `\n`, to be used when adding text to a `Content` tree (this replaces most uses of `DocletConstants.NL`) >> * `DocFile.PLATFORM_LINE_SEPARATOR`: the platform line separator, to be used when writing to files >> * The various `charCount` methods no longer have to worry about use of the platform line separator >> * Assertions are used to verify that there are no `\r` characters added into `Text`/`TextBuilder`/`RawHtml`/`Content` >> >> Other cleanup: >> * `DocletConstants.DEFAULT_TAB_STOP_LENGTH` is moved to `BaseOptions` which is the only class that uses it. This leaves just two remaining constants in `DocletConstants` which should probably be moved elsewhere as well, and the `DocletConstants` class deleted. That is a step too far for the work here. >> * Minor IDE-suggestions, for lambdas, enhanced switch, adding braces, etc >> >> One test was affected by the `DocletConstants.NL` change, but apart from that, this is a pure-cleanup change, with no (intentional) externally visible effect. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java line 161: > >> 159: } >> 160: count++; >> 161: break; > > The RawHtml constructor contains `assert Text.checkNewlines(rawHtml)` so I'm not sure this is actually needed. I'm not sure what you are referring to here. Yes, there is the assertion about newlines, but you still have to scan the `rawHtml` for start and end elements, and entities. Note there is no longer any special handling of newline characters (`\r`, `\n` etc) ------------- PR: https://git.openjdk.org/jdk/pull/9691 From jjg at openjdk.org Tue Aug 16 21:46:16 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 21:46:16 GMT Subject: RFR: JDK-8236048: Cleanup use of Utils.normalizeNewlines In-Reply-To: References: Message-ID: On Mon, 8 Aug 2022 10:23:02 GMT, Hannes Walln?fer wrote: > This looks quite good. Apart from the inline comments, I wondered about the following: > > * Would the methods and constant you moved to `Text` be better placed in `Content` as they are used in other Content instances? > * There are quite a few uses of the `"\n"` string literal in a content or pre-content context where the `NL` constant couuld be used. 1. I did wonder about moving the methods and constant into `Content` instead of `Text` but I think it is better to keep `Content` more abstract, and the new methods and constant are more "text-y". I also like the definitions being up in the `markup` package. 2. Yes, there may be references in the code to `\n`, but I don't think we need to go overboard to find and change them. To me, this is (generally) another reason to use simple `\n` in text strings, because that is the more usual convention in Java source code. Note that sometimes these occurrences originate in properties files, and so cannot use the `NL` constant, and it seems silly to use `.replace("\n", NL)` on all such strings. ------------- PR: https://git.openjdk.org/jdk/pull/9691 From jjg at openjdk.org Tue Aug 16 22:22:37 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 22:22:37 GMT Subject: RFR: JDK-8236048: Cleanup use of Utils.normalizeNewlines [v2] In-Reply-To: References: Message-ID: > Please review a medium-size cleanup related to handling newlines in `Content`/`HtmlTree`/`Text[Builder]` trees. > This is the 3rd and last in the recent series of cleanup tasks in the code to generate HTML. > > Until recently, the `Text`/`TextBuilder` objects were "ready-for-writing", meaning that characters like `<`, `&`, etc were encoded as entities, and newlines were represented by the platform line separator. This caused difficulties when counting the size of generated text, since these characters had to be detected and accounted for. A recent change addressed entities, but stayed clear of the newline issue, which is now addressed here. > > A related performance problem is that the method `Utils.normalizeNewlines` always created new strings, even when it was not necessary. > > With this change, newlines in `Text`, `TextBuilder` and other subtypes of `Content` containing text are always represented by `\n`, and are converted to the platform line separator as needed. > > I note the following assumptions: > > * the input may contain any flavor of newlines in the user-provided documentation comments > * the output should aways use the platform line separator (`\n` on Linux and macOS, `\r\n` on Windows etc.) > > Together, these imply that some amount of the input will need to be scanned to normalize newlines at some point in the process. While it would be nice to not have to normalize newlines, it's a case or "pay now, or pay later". > > Notable parts of this change: > > * `Utils.normalizeNewlines` is moved to be a static method in `Text` and rewritten to not create new strings unless needed. This allows a number of questionable imports of `toolkit.utils.DocletConstants` to be removed from the `html.markup` package. While it would be possible to call this method automatically on all strings passed to `Text`, `TextBuilder` etc, in many cases it is not necessary: put another way, it only needs to be called on strings that have come from the user, either in documentation comments or in command-line options. > * `Content.write`, and the implementations thereof, are given a new parameter which gives the newline sequence to use. This is set to `\n` for `toString` and the platform separator when writing to a file. > * `DocletConstants.NL` goes away and is superseded by: > * `Text.NL`: always `\n`, to be used when adding text to a `Content` tree (this replaces most uses of `DocletConstants.NL`) > * `DocFile.PLATFORM_LINE_SEPARATOR`: the platform line separator, to be used when writing to files > * The various `charCount` methods no longer have to worry about use of the platform line separator > * Assertions are used to verify that there are no `\r` characters added into `Text`/`TextBuilder`/`RawHtml`/`Content` > > Other cleanup: > * `DocletConstants.DEFAULT_TAB_STOP_LENGTH` is moved to `BaseOptions` which is the only class that uses it. This leaves just two remaining constants in `DocletConstants` which should probably be moved elsewhere as well, and the `DocletConstants` class deleted. That is a step too far for the work here. > * Minor IDE-suggestions, for lambdas, enhanced switch, adding braces, etc > > One test was affected by the `DocletConstants.NL` change, but apart from that, this is a pure-cleanup change, with no (intentional) externally visible effect. Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision: - Address review feedback - Merge remote-tracking branch 'upstream/master' into 8236048.normalizeNewlines - JDK-8236048: Cleanup use of Utils.normalizeNewlines ------------- Changes: - all: https://git.openjdk.org/jdk/pull/9691/files - new: https://git.openjdk.org/jdk/pull/9691/files/7eca2355..28d6401c Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=9691&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=9691&range=00-01 Stats: 17547 lines in 716 files changed: 10199 ins; 4432 del; 2916 mod Patch: https://git.openjdk.org/jdk/pull/9691.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9691/head:pull/9691 PR: https://git.openjdk.org/jdk/pull/9691 From jjg at openjdk.org Tue Aug 16 23:47:34 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 23:47:34 GMT Subject: RFR: JDK-8290126: Add a check in JavadocTester for "javadoc should not crash" [v5] In-Reply-To: References: Message-ID: > Please review a simple update to `JavadocTester` to provide a default-on check that no stack traces were written to the STDERR stream. > > There are also some minor cleanup edits suggested by the IDE. Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains six additional commits since the last revision: - improve check in JavadocTester remove obsolete/now-broken check from DocTest.java - Merge remote-tracking branch 'upstream/master' into 8290126.javadoctester-checkCrash - Merge remote-tracking branch 'upstream/master' into 8290126.javadoctester-checkCrash - revert (defer) improvement of TagletManager error message; fix TestTFMBuilder.java - Respond to review feedback; add new test - JDK-8290126: Add a check in JavadocTester for "javadoc should not crash" ------------- Changes: - all: https://git.openjdk.org/jdk/pull/9458/files - new: https://git.openjdk.org/jdk/pull/9458/files/0d461e3f..0b22f653 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=9458&range=04 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=9458&range=03-04 Stats: 18227 lines in 725 files changed: 10529 ins; 4758 del; 2940 mod Patch: https://git.openjdk.org/jdk/pull/9458.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9458/head:pull/9458 PR: https://git.openjdk.org/jdk/pull/9458 From jjg at openjdk.org Tue Aug 16 23:54:36 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Tue, 16 Aug 2022 23:54:36 GMT Subject: RFR: JDK-8290126: Add a check in JavadocTester for "javadoc should not crash" [v5] In-Reply-To: References: Message-ID: <72LRdOPmcI37bGCdhNTFlLNpkGFgWWO1TPRCSClZGjk=.de9916b9-4126-4fb7-b798-5eb291b3b8db@github.com> On Thu, 21 Jul 2022 16:35:28 GMT, Pavel Rappo wrote: > > > This PR could use the feature it introduces. It would test drive the feature and ensure that the feature works. A brief search showed these potential candidates in test/langtools/jdk/javadoc/: > > > > > > 1. doclet/InheritDocForUserTags/DocTest.java:57 > > > 2. tool/BadOptionsTest.java:83,96,108,120,132 > > > 3. doclet/testCustomTagletRegistration/TestRegistrationErrors.java:76 > > > 4. doclet/testSnippetTag/SnippetTester.java:55 > > > > > > Like other similar features, the feature is "default on", so it is currently active for all tests. > > Then I assume you'll see test failures if you change ` at com.sun.` and don't update the tests that expect exceptions. I removed the now almost useless check for `at com.com` in `DocTest.java` ... it was still minimally functional because of jtreg on the stack. I left in all the other existing checks for no stack traces or exception because they do not exactly match the new check. There are very few tests that actually check for exceptions: `TestTFMBuilder.java` is it, and that uses the new ability to disable the check for stack traces. See `TestTFMBuilder.java` line 164 in this PR. If it needs to be said, all javadoc tests pass with these changes. ------------- PR: https://git.openjdk.org/jdk/pull/9458 From hannesw at openjdk.org Wed Aug 17 05:39:25 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 05:39:25 GMT Subject: Integrated: JDK-8273860: Javadoc Deprecated API list should not use italic font for description column In-Reply-To: References: Message-ID: <_HioUOvSLHJAPZw4smQN7nGlfcDdMTBhaBh1_1nh2_c=.c8d671df-165a-42ba-a1a0-505a57211f6f@github.com> On Tue, 5 Jul 2022 11:01:46 GMT, Hannes Walln?fer wrote: > Please review a trivial change to use plain font for deprecation comments in the Deprecated API page. Italic font is used to make deprecation comments stand out against other parts of the documentation, but here the content consists exclusively of deprecation comments so the same so the font style should be the same as in other API summary pages. This pull request has now been integrated. Changeset: 1ef4e484 Author: Hannes Walln?fer URL: https://git.openjdk.org/jdk/commit/1ef4e484889c77cccadea44025924b2d010ba2cc Stats: 23 lines in 5 files changed: 0 ins; 0 del; 23 mod 8273860: Javadoc Deprecated API list should not use italic font for description column Reviewed-by: jjg ------------- PR: https://git.openjdk.org/jdk/pull/9375 From hannesw at openjdk.org Wed Aug 17 11:42:07 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 11:42:07 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Tue, 16 Aug 2022 19:48:37 GMT, Jonathan Gibbons wrote: >> Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. >> >> [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: >> >> [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ >> >> - Some colors have been unified to reduce the number of variable definitions: >> - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) >> - Header cells of user defined tables now use the same color as structural tables >> - Some sub-pixel sizing and spacing changes in random places >> >> Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette >> >> The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 959: > >> 957: } >> 958: div.page-search-info button#page-search-copy:hover { >> 959: background-color: rgba(128, 128, 160, 0.2); > > why have the old hex values just been converted to `rgba` values, and not CSS custom properties? One of my intentions was to keep the number of CSS custom properties as small as possible. I think the hover color of the copy-to-clipboard button (in this case for the search page extra information) is "fringe" enough to not want to define a dedicated property for it. Using a `rgba` value with a middle-of-the-road blue-grey color and a low alpha value allowed generate a semitransparent overlay that works both with light and dark background colors. The only background color this would not work for is if the background was itself a medium grey color, but in this case it could be overridden with a extra CSS rule. ------------- PR: https://git.openjdk.org/jdk/pull/9839 From hannesw at openjdk.org Wed Aug 17 11:48:17 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 11:48:17 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Tue, 16 Aug 2022 19:45:18 GMT, Jonathan Gibbons wrote: >> Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. >> >> [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: >> >> [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ >> >> - Some colors have been unified to reduce the number of variable definitions: >> - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) >> - Header cells of user defined tables now use the same color as structural tables >> - Some sub-pixel sizing and spacing changes in random places >> >> Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette >> >> The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 89: > >> 87: } >> 88: h1 { >> 89: font-size:1.428em; > > I appreciate these numbers give per-pixel consistency with before, but 3 decimal places seems a bit extreme! I agree. I only went to the third decimal position when it was actually necessary to retain the exact font size. But it would probably not have caught anybody's eye had I rounded to the nearest two decimal number. I guess I could do that to make it more uniform. ------------- PR: https://git.openjdk.org/jdk/pull/9839 From hannesw at openjdk.org Wed Aug 17 11:51:44 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 11:51:44 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Tue, 16 Aug 2022 19:41:59 GMT, Jonathan Gibbons wrote: >> Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. >> >> [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: >> >> [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ >> >> - Some colors have been unified to reduce the number of variable definitions: >> - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) >> - Header cells of user defined tables now use the same color as structural tables >> - Some sub-pixel sizing and spacing changes in random places >> >> Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette >> >> The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java line 333: > >> 331: // The order of the addStylesheet(...) calls is important >> 332: addStylesheet(head, DocPaths.SCRIPT_DIR.resolve(DocPaths.JQUERY_UI_CSS)); >> 333: addStylesheet(head, DocPaths.JQUERY_OVERRIDES_CSS); > > The edit as-is is OK, but the general code here makes me wonder if this class belongs in the `markup` package. I don't see the problem. The `Head` class generates part of the page markup, so the package seems fitting to me. ------------- PR: https://git.openjdk.org/jdk/pull/9839 From hannesw at openjdk.org Wed Aug 17 14:27:05 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 14:27:05 GMT Subject: RFR: JDK-8289332: Auto-generate ids for user-defined headings [v2] In-Reply-To: References: Message-ID: > This is a simple change to automatically generate `id` attributes for HTML headers in documentation comments. > > I decided to leave the functionality in `HtmlDocletWriter` rather than moving it to `HtmlIds` because it uses the same helper methods as`commentTagsToContent`. > > The value of the `id` attribute id derived from the content of the header tag with spaces and other non-word characters replaced by `-`. A `-hdr` suffix is appended to avoid collisions with other ids. If there are duplicate values an int counter is appended to make them unique. Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision: - Remove trailing whitespace - Address review feedback - Make sure hasIdAttribute is safe - Move id generating code to HtmlIds - Rename -hdr suffix to -heading - Rename header to heading in code ------------- Changes: - all: https://git.openjdk.org/jdk/pull/9627/files - new: https://git.openjdk.org/jdk/pull/9627/files/eb410346..47f2371f Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=9627&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=9627&range=00-01 Stats: 62 lines in 4 files changed: 31 ins; 14 del; 17 mod Patch: https://git.openjdk.org/jdk/pull/9627.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9627/head:pull/9627 PR: https://git.openjdk.org/jdk/pull/9627 From hannesw at openjdk.org Wed Aug 17 14:27:10 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 14:27:10 GMT Subject: RFR: JDK-8289332: Auto-generate ids for user-defined headings [v2] In-Reply-To: References: Message-ID: On Tue, 16 Aug 2022 19:58:52 GMT, Jonathan Gibbons wrote: >> Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision: >> >> - Remove trailing whitespace >> - Address review feedback >> >> - Make sure hasIdAttribute is safe >> - Move id generating code to HtmlIds >> - Rename -hdr suffix to -heading >> - Rename header to heading in code > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1762: > >> 1760: private boolean hasIdAttribute(StartElementTree node) { >> 1761: return node.getAttributes().stream().anyMatch( >> 1762: dt -> equalsIgnoreCase(((AttributeTree)dt).getName(), "id")); > > Do you need to filter/map the stream to ensure no class cast exceptions? > Can the attributes include `ErroneousTree`? Cood catch, I added a pattern matching instanceof which should be the easiest way to fix the problem. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1791: > >> 1789: if (!idValue.isEmpty()) { >> 1790: // Make id unique >> 1791: idValue = idValue + "-hdr"; > > Would it be better to use `header` rather than just `hdr` ? > Better still, `heading` seems to be the term in the HTML spec; `header` is also used, but not for headings. I renamed the `-hdr` suffix to `-heading` and also renamed code occurrences of "header" to "heading" (except for the test name). > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1800: > >> 1798: } >> 1799: content.add("id=\"").add(idValue).add("\""); >> 1800: } > > This part of the algorithm, to create an `id` from the text contents of a header, still feels like it belongs in `HtmlIds`. It feels like we should have > > HtmlIds.getIdForHeader(CharSequence headerText) > > or something like that I moved the code to a new `HtmlIds.forHeading(CharSequence, Set)` method. The `forHeading` follows the naming scheme of `HtmlIds`. The second argument of type `Set` is to make the returned id unique within its page. ------------- PR: https://git.openjdk.org/jdk/pull/9627 From hannesw at openjdk.org Wed Aug 17 14:28:36 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 14:28:36 GMT Subject: RFR: JDK-8289332: Auto-generate ids for user-defined headings In-Reply-To: References: Message-ID: On Mon, 25 Jul 2022 15:10:36 GMT, Hannes Walln?fer wrote: > This is a simple change to automatically generate `id` attributes for HTML headers in documentation comments. > > I decided to leave the functionality in `HtmlDocletWriter` rather than moving it to `HtmlIds` because it uses the same helper methods as`commentTagsToContent`. > > The value of the `id` attribute id derived from the content of the header tag with spaces and other non-word characters replaced by `-`. A `-hdr` suffix is appended to avoid collisions with other ids. If there are duplicate values an int counter is appended to make them unique. Thanks for the review, I think I addressed all your feedback in the incremental commit. As a corner case I removed the emptiness check for the heading text, so an empty heading will now get an `id="-heading[idx]"` attribute which is useless but also harmless. ------------- PR: https://git.openjdk.org/jdk/pull/9627 From jjg at openjdk.org Wed Aug 17 16:30:26 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Wed, 17 Aug 2022 16:30:26 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Wed, 17 Aug 2022 11:49:41 GMT, Hannes Walln?fer wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java line 333: >> >>> 331: // The order of the addStylesheet(...) calls is important >>> 332: addStylesheet(head, DocPaths.SCRIPT_DIR.resolve(DocPaths.JQUERY_UI_CSS)); >>> 333: addStylesheet(head, DocPaths.JQUERY_OVERRIDES_CSS); >> >> The edit as-is is OK, but the general code here makes me wonder if this class belongs in the `markup` package. > > I don't see the problem. The `Head` class generates part of the page markup, so the package seems fitting to me. It's in a gray area. The `markup` package was supposed to be low-level primitives for building basic HTML trees ... and these lines reflect policy more than underlying support. We moved `Table` and `Navigation` out of `markup` for the same reason. Anyway, this is just a discussion, not a blocker. >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 89: >> >>> 87: } >>> 88: h1 { >>> 89: font-size:1.428em; >> >> I appreciate these numbers give per-pixel consistency with before, but 3 decimal places seems a bit extreme! > > I agree. I only went to the third decimal position when it was actually necessary to retain the exact font size. But it would probably not have caught anybody's eye had I rounded to the nearest two decimal number. I guess I could do that to make it more uniform. I would leave it for now, for this release, and maybe we tweak/simplify the constants later on. ------------- PR: https://git.openjdk.org/jdk/pull/9839 From jjg at openjdk.org Wed Aug 17 16:36:36 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Wed, 17 Aug 2022 16:36:36 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Thu, 11 Aug 2022 15:29:46 GMT, Hannes Walln?fer wrote: > Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. > > [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: > > [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ > > - Some colors have been unified to reduce the number of variable definitions: > - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) > - Header cells of user defined tables now use the same color as structural tables > - Some sub-pixel sizing and spacing changes in random places > > Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette > > The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. I'll approve it, but I would still recommend that either now or later we establish a rule that says that all colors and font choices are set via CSS custom properties. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.org/jdk/pull/9839 From jjg at openjdk.org Wed Aug 17 16:36:38 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Wed, 17 Aug 2022 16:36:38 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Wed, 17 Aug 2022 11:38:18 GMT, Hannes Walln?fer wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 959: >> >>> 957: } >>> 958: div.page-search-info button#page-search-copy:hover { >>> 959: background-color: rgba(128, 128, 160, 0.2); >> >> why have the old hex values just been converted to `rgba` values, and not CSS custom properties? > > One of my intentions was to keep the number of CSS custom properties as small as possible. I think the hover color of the copy-to-clipboard button (in this case for the search page extra information) is "fringe" enough to not want to define a dedicated property for it. > > Using a `rgba` value with a middle-of-the-road blue-grey color and a low alpha value allows me to generate a semitransparent overlay that works both with light and dark background colors. The only background color this would not work with is if the background was itself a medium grey color, but in this case it could be overridden with a extra CSS rule. mmmm ... OK, but ... _Keep everything as simple as possible, but no simpler_ Yes, there is merit it reducing the number of CSS custom properties, but there is equal merit in a simple rule that says that all colors are set via custom properties. As it stands, we have to explain the (reason for the) exception, ------------- PR: https://git.openjdk.org/jdk/pull/9839 From jjg at openjdk.org Wed Aug 17 16:50:12 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Wed, 17 Aug 2022 16:50:12 GMT Subject: RFR: JDK-8289332: Auto-generate ids for user-defined headings [v2] In-Reply-To: References: Message-ID: On Wed, 17 Aug 2022 14:27:05 GMT, Hannes Walln?fer wrote: >> This is a simple change to automatically generate `id` attributes for HTML headers in documentation comments. >> >> I decided to leave the functionality in `HtmlDocletWriter` rather than moving it to `HtmlIds` because it uses the same helper methods as`commentTagsToContent`. >> >> The value of the `id` attribute id derived from the content of the header tag with spaces and other non-word characters replaced by `-`. A `-hdr` suffix is appended to avoid collisions with other ids. If there are duplicate values an int counter is appended to make them unique. > > Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision: > > - Remove trailing whitespace > - Address review feedback > > - Make sure hasIdAttribute is safe > - Move id generating code to HtmlIds > - Rename -hdr suffix to -heading > - Rename header to heading in code yes, I like the change to move the code to allocate the `id` to `HtmlIds` ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.org/jdk/pull/9627 From hannesw at openjdk.org Wed Aug 17 17:19:31 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 17 Aug 2022 17:19:31 GMT Subject: Integrated: JDK-8289332: Auto-generate ids for user-defined headings In-Reply-To: References: Message-ID: On Mon, 25 Jul 2022 15:10:36 GMT, Hannes Walln?fer wrote: > This is a simple change to automatically generate `id` attributes for HTML headers in documentation comments. > > I decided to leave the functionality in `HtmlDocletWriter` rather than moving it to `HtmlIds` because it uses the same helper methods as`commentTagsToContent`. > > The value of the `id` attribute id derived from the content of the header tag with spaces and other non-word characters replaced by `-`. A `-hdr` suffix is appended to avoid collisions with other ids. If there are duplicate values an int counter is appended to make them unique. This pull request has now been integrated. Changeset: 8b4e6ba0 Author: Hannes Walln?fer URL: https://git.openjdk.org/jdk/commit/8b4e6ba01ffef77d5f1b9a9aa3e978f4da431836 Stats: 201 lines in 5 files changed: 190 ins; 6 del; 5 mod 8289332: Auto-generate ids for user-defined headings Reviewed-by: jjg ------------- PR: https://git.openjdk.org/jdk/pull/9627 From jjg at openjdk.org Wed Aug 17 18:23:07 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Wed, 17 Aug 2022 18:23:07 GMT Subject: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v13] In-Reply-To: References: Message-ID: > Please review the code and tests to add support for a new `@spec url title` tag to javadoc. Note, this does not include any changes to API doc comments to use the new tag in JDK API documentation; that will come later. Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 20 commits: - Merge with upstream/master - Fix typo and merge error - Merge with upstream/master - Update @since tags - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2 - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2 - Updates for latest repo - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2 - Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2 - Merge with upstream/master - ... and 10 more: https://git.openjdk.org/jdk/compare/0fc92637...e8fe51b0 ------------- Changes: https://git.openjdk.org/jdk/pull/8439/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=8439&range=12 Stats: 1502 lines in 41 files changed: 1474 ins; 6 del; 22 mod Patch: https://git.openjdk.org/jdk/pull/8439.diff Fetch: git fetch https://git.openjdk.org/jdk pull/8439/head:pull/8439 PR: https://git.openjdk.org/jdk/pull/8439 From hannesw at openjdk.org Thu Aug 18 09:03:29 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 18 Aug 2022 09:03:29 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Thu, 11 Aug 2022 15:29:46 GMT, Hannes Walln?fer wrote: > Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. > > [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: > > [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ > > - Some colors have been unified to reduce the number of variable definitions: > - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) > - Header cells of user defined tables now use the same color as structural tables > - Some sub-pixel sizing and spacing changes in random places > > Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette > > The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. Thanks, I agree about the "all colors and fonts should be defined by properties" role. Since I would like to get this integrated rather sooner than later I'll file a follow-up JBS issue for that. ------------- PR: https://git.openjdk.org/jdk/pull/9839 From hannesw at openjdk.org Thu Aug 18 09:04:51 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 18 Aug 2022 09:04:51 GMT Subject: Integrated: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Thu, 11 Aug 2022 15:29:46 GMT, Hannes Walln?fer wrote: > Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. > > [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: > > [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ > > - Some colors have been unified to reduce the number of variable definitions: > - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) > - Header cells of user defined tables now use the same color as structural tables > - Some sub-pixel sizing and spacing changes in random places > > Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette > > The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. This pull request has now been integrated. Changeset: d5435642 Author: Hannes Walln?fer URL: https://git.openjdk.org/jdk/commit/d5435642f9671766ecbcbf744ecd8e62fb929a69 Stats: 245 lines in 11 files changed: 51 ins; 48 del; 146 mod 8289334: Use CSS variables to define fonts and colors Reviewed-by: jjg ------------- PR: https://git.openjdk.org/jdk/pull/9839 From hannesw at openjdk.org Thu Aug 18 11:22:24 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 18 Aug 2022 11:22:24 GMT Subject: RFR: JDK-8289334: Use CSS variables to define fonts and colors In-Reply-To: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> References: <7OXK3-rO4VZIw2Uyr-Kgl-pM9WMQ-zuXqBXS0idqIVo=.3ff5b4a1-7082-4f60-aa46-52158fe3d49c@github.com> Message-ID: On Thu, 11 Aug 2022 15:29:46 GMT, Hannes Walln?fer wrote: > Please review a change to use CSS custom properties (aka variables) to define the fonts and colors in generated documentation. It is now possible to change the fonts and colors of generated API documentation by changing the values of these properties directly or by using extra stylesheet. > > [Documentation rendered with the updated stylesheet][docs] is mostly identical pixel-by-pixel to the previous documentation with very few exceptions: > > [docs]: http://cr.openjdk.java.net/~hannesw/8289334/api.00/ > > - Some colors have been unified to reduce the number of variable definitions: > - Single pixel borders used in class documentation pages use a single shade of gray (most visible in headers of member details which now have light gray instead of a darker gray border) > - Header cells of user defined tables now use the same color as structural tables > - Some sub-pixel sizing and spacing changes in random places > > Contrary to previously stated intention I did not change the stylesheet to become more flexible (e.g. to allow combinations of background and foreground colors that are not currently supported). The reason is that this would have at least doubled the number of color properties and required new CSS rules, increasing the complexity of the style sheet and risking to add new bugs. Reducing the number of variables makes it easier to customize the layout and also preserves part of the original design by reducing the number of colors to a smaller color palette > > The only code change is due to the removal of `jquery-ui-overrides.css` which had to be integrated into the main stylesheet in order to make use of CSS custom properties. Filed as follow-up bug: https://bugs.openjdk.org/browse/JDK-8292594 > I'll approve it, but I would still recommend that either now or later we establish a rule that says that all colors and font choices are set via CSS custom properties. ------------- PR: https://git.openjdk.org/jdk/pull/9839 From hannesw at openjdk.org Thu Aug 18 16:19:20 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 18 Aug 2022 16:19:20 GMT Subject: RFR: JDK-8236048: Cleanup use of Utils.normalizeNewlines [v2] In-Reply-To: References: Message-ID: On Tue, 16 Aug 2022 22:22:37 GMT, Jonathan Gibbons wrote: >> Please review a medium-size cleanup related to handling newlines in `Content`/`HtmlTree`/`Text[Builder]` trees. >> This is the 3rd and last in the recent series of cleanup tasks in the code to generate HTML. >> >> Until recently, the `Text`/`TextBuilder` objects were "ready-for-writing", meaning that characters like `<`, `&`, etc were encoded as entities, and newlines were represented by the platform line separator. This caused difficulties when counting the size of generated text, since these characters had to be detected and accounted for. A recent change addressed entities, but stayed clear of the newline issue, which is now addressed here. >> >> A related performance problem is that the method `Utils.normalizeNewlines` always created new strings, even when it was not necessary. >> >> With this change, newlines in `Text`, `TextBuilder` and other subtypes of `Content` containing text are always represented by `\n`, and are converted to the platform line separator as needed. >> >> I note the following assumptions: >> >> * the input may contain any flavor of newlines in the user-provided documentation comments >> * the output should aways use the platform line separator (`\n` on Linux and macOS, `\r\n` on Windows etc.) >> >> Together, these imply that some amount of the input will need to be scanned to normalize newlines at some point in the process. While it would be nice to not have to normalize newlines, it's a case or "pay now, or pay later". >> >> Notable parts of this change: >> >> * `Utils.normalizeNewlines` is moved to be a static method in `Text` and rewritten to not create new strings unless needed. This allows a number of questionable imports of `toolkit.utils.DocletConstants` to be removed from the `html.markup` package. While it would be possible to call this method automatically on all strings passed to `Text`, `TextBuilder` etc, in many cases it is not necessary: put another way, it only needs to be called on strings that have come from the user, either in documentation comments or in command-line options. >> * `Content.write`, and the implementations thereof, are given a new parameter which gives the newline sequence to use. This is set to `\n` for `toString` and the platform separator when writing to a file. >> * `DocletConstants.NL` goes away and is superseded by: >> * `Text.NL`: always `\n`, to be used when adding text to a `Content` tree (this replaces most uses of `DocletConstants.NL`) >> * `DocFile.PLATFORM_LINE_SEPARATOR`: the platform line separator, to be used when writing to files >> * The various `charCount` methods no longer have to worry about use of the platform line separator >> * Assertions are used to verify that there are no `\r` characters added into `Text`/`TextBuilder`/`RawHtml`/`Content` >> >> Other cleanup: >> * `DocletConstants.DEFAULT_TAB_STOP_LENGTH` is moved to `BaseOptions` which is the only class that uses it. This leaves just two remaining constants in `DocletConstants` which should probably be moved elsewhere as well, and the `DocletConstants` class deleted. That is a step too far for the work here. >> * Minor IDE-suggestions, for lambdas, enhanced switch, adding braces, etc >> >> One test was affected by the `DocletConstants.NL` change, but apart from that, this is a pure-cleanup change, with no (intentional) externally visible effect. > > Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision: > > - Address review feedback > - Merge remote-tracking branch 'upstream/master' into 8236048.normalizeNewlines > - JDK-8236048: Cleanup use of Utils.normalizeNewlines Looks good! ------------- Marked as reviewed by hannesw (Reviewer). PR: https://git.openjdk.org/jdk/pull/9691 From hannesw at openjdk.org Thu Aug 18 16:19:22 2022 From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 18 Aug 2022 16:19:22 GMT Subject: RFR: JDK-8236048: Cleanup use of Utils.normalizeNewlines [v2] In-Reply-To: References: Message-ID: On Tue, 16 Aug 2022 21:35:32 GMT, Jonathan Gibbons wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java line 161: >> >>> 159: } >>> 160: count++; >>> 161: break; >> >> The RawHtml constructor contains `assert Text.checkNewlines(rawHtml)` so I'm not sure this is actually needed. > > I'm not sure what you are referring to here. Yes, there is the assertion about newlines, but you still have to scan the `rawHtml` for start and end elements, and entities. Note there is no longer any special handling of newline characters (`\r`, `\n` etc) Sorry, I somehow misread the diff. ------------- PR: https://git.openjdk.org/jdk/pull/9691 From prappo at openjdk.org Thu Aug 18 17:46:17 2022 From: prappo at openjdk.org (Pavel Rappo) Date: Thu, 18 Aug 2022 17:46:17 GMT Subject: RFR: 8289658: Avoid redundant LinkedHashMap.get call in TagletManager.addNewSimpleCustomTag In-Reply-To: References: Message-ID: On Mon, 4 Jul 2022 15:05:20 GMT, Andrey Turbanov wrote: >> 265 commits seem to be quite a divergence between this PR branch and openjdk:master. I know that sometimes it seems not to be worth the hassle, but please merge openjdk:master into this PR branch. If nothing else, it will trigger GHA to re-test the change. > >>please merge openjdk:master into this PR branch > > Done @turbanoff, what's the status of this PR? What do you plan to do with it next? ------------- PR: https://git.openjdk.org/jdk/pull/9137 From jjg at openjdk.org Thu Aug 18 21:58:50 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Thu, 18 Aug 2022 21:58:50 GMT Subject: RFR: JDK-8287597: List all preview features on the javadoc PREVIEW page In-Reply-To: <0UfKceKzCT3_exJ2vDs5y7IeroB2IHU8kHPO7b46KDY=.bbc662cb-5bd9-4205-acc2-3025ad1a5ab1@github.com> References: <0UfKceKzCT3_exJ2vDs5y7IeroB2IHU8kHPO7b46KDY=.bbc662cb-5bd9-4205-acc2-3025ad1a5ab1@github.com> Message-ID: On Thu, 30 Jun 2022 15:14:40 GMT, Hannes Walln?fer wrote: > Please review an enhancement to the preview page to add a list of preview features and allow users to explore the preview APIs by feature. > > While the changes for the enhancement itself are not overly complex, the work entailed a moderate cleanup of other summary API lists (Deprecated and New API pages) as well as a few unrelated summary pages that happened to share some of the CSS classes and HTML structure. > > The change itself starts with a new internal `jdk.internal.javac.PreviewFeature.JEP` annotation interface to add JEP information to the nearby `jdk.internal.javac.PreviewFeature.Feature` enum. This JEP information is retrieved by new methods in the javadoc `Utils` class and then fetched by `PreviewAPIListBuilder` which passes it on to `PreviewListWriter`. > > The superclass of `PreviewListWriter` and other API summary writer classes, `SummaryListWriter`, gets a new `addContentSelectors(Content)` method to add the checkboxes to show/hide various parts of the page content. The class is also now abstract as this and other methods do not have useful implementations in the base class. > > Another change to `SummaryListWriter` is that `pageMode`, `description`, `headContent` and `titleKey` are no longer fields in the class but rather sent to the `generateSummaryListFile` method as parameters since they are mostly just used locally in that method. On the other hand, the associated Builder is used in many places and previously had to be retrieved from the configuration object or passed around as parameter, so that is now set as a final field in `SummaryListWriter`. > > Finally, a few words about changes in CSS and HTML: The "Contents" list containing various kinds of elements in the API list was previously contained in the `
` element that also contains the page header, and the stylesheet used the `.header ul` selector to style the list. Now that the checkboxes separate the page header from the contents list it felt wrong to put all this in the header div (most other pages only use the div for the header itself). I also didn't like the indirect CSS selector too much, `.header ul` is not very indicative of what it applies to. > > I therefore decided to create a new dedicated CSS class for the contents list called `contents-list`, and move the `
    ` element out of the header div. Apart from the summary API pages, this change also affects the "Constant Values" page as well as the top and package level "Tree" (class hierarchy) pages. I made sure the contents list in these pages look the same as before. > > The list items in the contents list now each have an `id` attribute to allow hiding the list item if no content for the element kind is currently selected/visible. The value of the `id` attribute uses the format `contents-`. > > There is one additional CSS class called `preview-feature-list` used for the list of preview feature JEPs. > > Demo output for the new preview page as well as other pages is available here: > http://cr.openjdk.java.net/~hannesw/8287597/api.03/preview-list.html Mostly excellent. There are some minor comments inline. There are more "English phrases" (recognized as "strings with words separated by spaces") than I expected, at least some of which will end up in generated docs. But that being said, I guess this is a JDK-only feature, and we don't translate the source going into our API docs. src/java.base/share/classes/jdk/internal/javac/PreviewFeature.java line 91: > 89: /** JEP number */ > 90: int number() default 0; > 91: /** JEP title */ suggest noting the format (i.e. plain text, not HTML, not a resource key) src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SummaryListWriter.java line 164: > 162: protected void addIndexLink(HtmlId id, String headingKey, Content content) { > 163: var li = HtmlTree.LI(links.createLink(id, > 164: contents.getContent(headingKey))).setId(HtmlId.of("contents-" + id.name())); Suggest adding a comment that `"contents-" + id` appears in the JavaScript code as well. You presumably can't change one without the other (and can't use a common function across the language barrier.) src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 125: > 123: doclet.Preview_API=Preview API > 124: doclet.Preview_API_Checkbox_Label=Show preview API for: > 125: doclet.Preview_JEP_URL=https://openjdk.java.net/jeps/{0} Use `openjdk.org` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 243: > 241: } > 242: ul.contents-list li { > 243: font-size: 13px; Do these values have to be normalized into `.em` units, to align with new themes? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 1346: > 1344: * @return the map of PreviewFeature.JEP annotation element values, or an empty map > 1345: */ > 1346: public Map getJepInfo(String feature) { This method should borderline be in `Workarounds.java` because you are accessing javac internal features, even if only reflectively. ------------- PR: https://git.openjdk.org/jdk/pull/9336 From jjg at openjdk.org Thu Aug 18 22:02:46 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Thu, 18 Aug 2022 22:02:46 GMT Subject: Integrated: JDK-8236048: Cleanup use of Utils.normalizeNewlines In-Reply-To: References: Message-ID: On Sat, 30 Jul 2022 00:36:06 GMT, Jonathan Gibbons wrote: > Please review a medium-size cleanup related to handling newlines in `Content`/`HtmlTree`/`Text[Builder]` trees. > This is the 3rd and last in the recent series of cleanup tasks in the code to generate HTML. > > Until recently, the `Text`/`TextBuilder` objects were "ready-for-writing", meaning that characters like `<`, `&`, etc were encoded as entities, and newlines were represented by the platform line separator. This caused difficulties when counting the size of generated text, since these characters had to be detected and accounted for. A recent change addressed entities, but stayed clear of the newline issue, which is now addressed here. > > A related performance problem is that the method `Utils.normalizeNewlines` always created new strings, even when it was not necessary. > > With this change, newlines in `Text`, `TextBuilder` and other subtypes of `Content` containing text are always represented by `\n`, and are converted to the platform line separator as needed. > > I note the following assumptions: > > * the input may contain any flavor of newlines in the user-provided documentation comments > * the output should aways use the platform line separator (`\n` on Linux and macOS, `\r\n` on Windows etc.) > > Together, these imply that some amount of the input will need to be scanned to normalize newlines at some point in the process. While it would be nice to not have to normalize newlines, it's a case or "pay now, or pay later". > > Notable parts of this change: > > * `Utils.normalizeNewlines` is moved to be a static method in `Text` and rewritten to not create new strings unless needed. This allows a number of questionable imports of `toolkit.utils.DocletConstants` to be removed from the `html.markup` package. While it would be possible to call this method automatically on all strings passed to `Text`, `TextBuilder` etc, in many cases it is not necessary: put another way, it only needs to be called on strings that have come from the user, either in documentation comments or in command-line options. > * `Content.write`, and the implementations thereof, are given a new parameter which gives the newline sequence to use. This is set to `\n` for `toString` and the platform separator when writing to a file. > * `DocletConstants.NL` goes away and is superseded by: > * `Text.NL`: always `\n`, to be used when adding text to a `Content` tree (this replaces most uses of `DocletConstants.NL`) > * `DocFile.PLATFORM_LINE_SEPARATOR`: the platform line separator, to be used when writing to files > * The various `charCount` methods no longer have to worry about use of the platform line separator > * Assertions are used to verify that there are no `\r` characters added into `Text`/`TextBuilder`/`RawHtml`/`Content` > > Other cleanup: > * `DocletConstants.DEFAULT_TAB_STOP_LENGTH` is moved to `BaseOptions` which is the only class that uses it. This leaves just two remaining constants in `DocletConstants` which should probably be moved elsewhere as well, and the `DocletConstants` class deleted. That is a step too far for the work here. > * Minor IDE-suggestions, for lambdas, enhanced switch, adding braces, etc > > One test was affected by the `DocletConstants.NL` change, but apart from that, this is a pure-cleanup change, with no (intentional) externally visible effect. This pull request has now been integrated. Changeset: 1b756bfa Author: Jonathan Gibbons URL: https://git.openjdk.org/jdk/commit/1b756bfa3a1be2004af3ea12e86199ca0604c841 Stats: 246 lines in 26 files changed: 77 ins; 76 del; 93 mod 8236048: Cleanup use of Utils.normalizeNewlines Reviewed-by: hannesw ------------- PR: https://git.openjdk.org/jdk/pull/9691 From duke at openjdk.org Fri Aug 19 06:56:38 2022 From: duke at openjdk.org (Joe) Date: Fri, 19 Aug 2022 06:56:38 GMT Subject: RFR: 8289562: Change bugs.java.com and bugreport.java.com URL's to https [v2] In-Reply-To: References: Message-ID: > 8289562: Change bugs.java.com and bugreport.java.com URL's to https Joe has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision: - Merge branch 'openjdk:master' into master - Merge branch 'openjdk:master' into master - changed the hrl from http to https JDK-8289562 ------------- Changes: - all: https://git.openjdk.org/jdk/pull/9445/files - new: https://git.openjdk.org/jdk/pull/9445/files/324f877c..07b7be0c Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=9445&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=9445&range=00-01 Stats: 142897 lines in 2088 files changed: 75388 ins; 52973 del; 14536 mod Patch: https://git.openjdk.org/jdk/pull/9445.diff Fetch: git fetch https://git.openjdk.org/jdk pull/9445/head:pull/9445 PR: https://git.openjdk.org/jdk/pull/9445 From duke at openjdk.org Fri Aug 19 08:58:59 2022 From: duke at openjdk.org (Joe) Date: Fri, 19 Aug 2022 08:58:59 GMT Subject: Integrated: 8289562: Change bugs.java.com and bugreport.java.com URL's to https In-Reply-To: References: Message-ID: <3PKzwl7RxEVyWEBTVdySoL1eKjal-7IRGDANL2ABqG8=.7dc34842-62c6-40a5-8ce3-1bf0e9f58852@github.com> On Mon, 11 Jul 2022 08:04:20 GMT, Joe wrote: > 8289562: Change bugs.java.com and bugreport.java.com URL's to https This pull request has now been integrated. Changeset: 1f484dae Author: Joe Committer: Fairoz Matte URL: https://git.openjdk.org/jdk/commit/1f484dae4efaa60cf18a3d4df947c05f1497bd5b Stats: 18 lines in 17 files changed: 0 ins; 0 del; 18 mod 8289562: Change bugs.java.com and bugreport.java.com URL's to https Co-authored-by: Joe Cherian Reviewed-by: prr, jjg, naoto, iris ------------- PR: https://git.openjdk.org/jdk/pull/9445 From aturbanov at openjdk.org Tue Aug 23 07:43:32 2022 From: aturbanov at openjdk.org (Andrey Turbanov) Date: Tue, 23 Aug 2022 07:43:32 GMT Subject: RFR: 8289658: Avoid redundant LinkedHashMap.get call in TagletManager.addNewSimpleCustomTag [v4] In-Reply-To: <3nd9uNRqSEEzBEz0_KowRIn9zqaXNRQetzWP6ANQ5dY=.2e235c00-d64d-4653-8c89-b75064929c7e@github.com> References: <3nd9uNRqSEEzBEz0_KowRIn9zqaXNRQetzWP6ANQ5dY=.2e235c00-d64d-4653-8c89-b75064929c7e@github.com> Message-ID: On Mon, 1 Aug 2022 07:01:15 GMT, Andrey Turbanov wrote: >> Instead of pair `LinkedHashMap.get`+`LinkedHashMap.remove` calls, we can use value returned from single `allTaglets.remove` call. >> It's shorter and a bit faster. >> https://github.com/openjdk/jdk/blob/d46f404b3179c66e8e5775a9e2253c95238153c7/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java#L314-L325 > > Andrey Turbanov has updated the pull request incrementally with one additional commit since the last revision: > > 8289658: Avoid redundant LinkedHashMap.get call in TagletManager.addNewSimpleCustomTag > > improve comment I believe it's good enough. Thank you for review! ------------- PR: https://git.openjdk.org/jdk/pull/9137 From aturbanov at openjdk.org Tue Aug 23 07:46:51 2022 From: aturbanov at openjdk.org (Andrey Turbanov) Date: Tue, 23 Aug 2022 07:46:51 GMT Subject: Integrated: 8289658: Avoid redundant LinkedHashMap.get call in TagletManager.addNewSimpleCustomTag In-Reply-To: References: Message-ID: On Sat, 11 Jun 2022 10:52:29 GMT, Andrey Turbanov wrote: > Instead of pair `LinkedHashMap.get`+`LinkedHashMap.remove` calls, we can use value returned from single `allTaglets.remove` call. > It's shorter and a bit faster. > https://github.com/openjdk/jdk/blob/d46f404b3179c66e8e5775a9e2253c95238153c7/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java#L314-L325 This pull request has now been integrated. Changeset: b4e1aa87 Author: Andrey Turbanov URL: https://git.openjdk.org/jdk/commit/b4e1aa87e3caa56bde52120bb3d84da53e7ebaa3 Stats: 5 lines in 1 file changed: 1 ins; 2 del; 2 mod 8289658: Avoid redundant LinkedHashMap.get call in TagletManager.addNewSimpleCustomTag Reviewed-by: attila, prappo ------------- PR: https://git.openjdk.org/jdk/pull/9137 From jgneff at openjdk.org Mon Aug 29 21:12:53 2022 From: jgneff at openjdk.org (John Neffenger) Date: Mon, 29 Aug 2022 21:12:53 GMT Subject: RFR: 8292892: Javadoc index descriptions are not deterministic Message-ID: Please review these changes to the Javadoc index builders. This pull request adds 423 missing entries to the index of the JDK API Specification, corrects their package names in the member search index, and makes their descriptions deterministic. I'll follow up with more information in a separate comment. ------------- Commit messages: - Add a unit test case to verify the fix - Add members to index using containing type element Changes: https://git.openjdk.org/jdk/pull/10070/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=10070&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8292892 Stats: 312 lines in 6 files changed: 310 ins; 0 del; 2 mod Patch: https://git.openjdk.org/jdk/pull/10070.diff Fetch: git fetch https://git.openjdk.org/jdk pull/10070/head:pull/10070 PR: https://git.openjdk.org/jdk/pull/10070 From jgneff at openjdk.org Mon Aug 29 21:41:09 2022 From: jgneff at openjdk.org (John Neffenger) Date: Mon, 29 Aug 2022 21:41:09 GMT Subject: RFR: 8292892: Javadoc index descriptions are not deterministic In-Reply-To: References: Message-ID: On Mon, 29 Aug 2022 21:03:34 GMT, John Neffenger wrote: > Please review these changes to the Javadoc index builders. This pull request adds 423 missing entries to the index of the JDK API Specification, corrects their package names in the member search index, and makes their descriptions deterministic. I'll follow up with more information in a separate comment. This is an interesting bug. It's the first one I've encountered that is impossible to miss with reproducible builds but might have been impossible to find without them. It also reveals a surprising feature of the Java language: inaccessible members can be made public by an intermediate subclass. That feature first caused problems for Javadoc in 2002 with bug JDK-4780441. The fix for that bug made it so that "inherited members from package private classes are now documented as though they were declared in the inheriting class." The fix was released in Java SE 5 ("Tiger"), adding the members to the pages of their inheriting classes. The members were added to the index in Java SE 15. Below is a description of the problem, as I understand it, and my proposed solution. ### The problem The Javadoc code refers to the type in which a member is found as the *containing type element* and stores it in its own `IndexItem` class. The type in which a member is declared is referred to as the *enclosing element.* The problem occurs because the code assumes that these two elements are always the same, yet for the few cases where members are otherwise inaccessible, they aren't. For example, there are four index items of `LOCCRC` in the `java.util.jar` package. They are shown below with their string values, where `iN` represents an instance of `IndexItem`. i1.getLabel() "LOCCRC" i1.getContainingTypeElement() "java.util.jar.JarEntry" i1.getElement().getEnclosingElement() "java.util.zip.ZipConstants" i2.getLabel() "LOCCRC" i2.getContainingTypeElement() "java.util.jar.JarFile" i2.getElement().getEnclosingElement() "java.util.zip.ZipConstants" i3.getLabel() "LOCCRC" i3.getContainingTypeElement() "java.util.jar.JarInputStream" i3.getElement().getEnclosingElement() "java.util.zip.ZipConstants" i4.getLabel() "LOCCRC" i4.getContainingTypeElement() "java.util.jar.JarOutputStream" i4.getElement().getEnclosingElement() "java.util.zip.ZipConstants" Index items are stored in a set, and the set's comparator function uses the index label and the enclosing element to determine whether an item is already in the set. The four items above appear the same to the comparator, so only the first one makes it into the set. The first one is just the one first found in the package directory when they are loaded in *directory order* (unsorted). So the random order in which the source files are stored by the file system in their directory determines which one of the items gets listed in the index. There's a related problem in the member search index. The class name of the containing type element is appended to the package name of the enclosing element. That works for most members, but for these specially-inherited members, it creates entries that don't exist. For example, the search index might list `java.util.zip.JarEntry.LOCCRC` and link it to the file `java/util/zip/JarEntry.html`. ### The solution The solution is to add a step to the comparator: when two index items are the same after comparing their labels and enclosing elements, make an additional comparison of their containing type elements. For the related problem in the member search index, the solution is to get the package name from the containing type element instead of from the enclosing element. The 423 new index entries are shown as insertions in the `git diff` files linked below: * [JDK API Index: Before vs. After JDK-8292892 ](https://gist.github.com/jgneff/cd3d1622bf1b5150e9dde8fd26c41cfc) * [JDK API Search: Before vs. After JDK-8292892](https://gist.github.com/jgneff/3c74d38ec7b46a29ebc4bb1282b47d16) As far as I can tell, all of the new entries are inherited from just the following members: package java.awt; abstract class AttributeValue { public int hashCode() {...} public String toString() {...} } package java.lang; abstract sealed class AbstractStringBuilder implements Appendable, CharSequence permits StringBuilder, StringBuffer { public IntStream chars() {...} public IntStream codePoints() {...} } package java.lang.foreign; public sealed interface MemoryLayout permits AbstractLayout, SequenceLayout, GroupLayout, PaddingLayout, ValueLayout { long bitAlignment(); long bitSize(); long byteSize(); boolean isPadding(); Optional name(); } package java.time.chrono; public interface ChronoLocalDate extends Temporal, TemporalAdjuster, Comparable { String toString(); long until(Temporal endExclusive, TemporalUnit unit); } package java.util.zip; interface ZipConstants { static final int CENATT = 36; ... static final int LOCVER = 4; } package jdk.incubator.vector; abstract class AbstractVector extends Vector { public final Vector castShape(VectorSpecies toSpecies, int part) {...} public final Vector check(Class elementType) {...} public final Vector check(VectorSpecies species) {...} public abstract Vector convertShape(Conversion conv, VectorSpecies rsp, int part); public final Vector convert(Conversion conv, int part) {...} public final VectorMask maskAll(boolean bit) {...} public DoubleVector reinterpretAsDoubles() {...} public FloatVector reinterpretAsFloats() {...} public IntVector reinterpretAsInts() {...} public LongVector reinterpretAsLongs() {...} public ShortVector reinterpretAsShorts() {...} public final VectorSpecies species() {...} } ------------- PR: https://git.openjdk.org/jdk/pull/10070 From prappo at openjdk.org Mon Aug 29 23:01:10 2022 From: prappo at openjdk.org (Pavel Rappo) Date: Mon, 29 Aug 2022 23:01:10 GMT Subject: RFR: 8292892: Javadoc index descriptions are not deterministic In-Reply-To: References: Message-ID: On Mon, 29 Aug 2022 21:03:34 GMT, John Neffenger wrote: > Please review these changes to the Javadoc index builders. This pull request adds 423 missing entries to the index of the JDK API Specification, corrects their package names in the member search index, and makes their descriptions deterministic. I'll follow up with more information in a separate comment. I've checked the code, the tests and the resulting JDK API Documentation. All look good. That said, I leave it to Jon to make the final determination, as he's an expert in this area and knows a lot more about the problem of intermediate types than I do. Separately, thanks for using the JLS terminology (_package access_) for what is colloquially known as _package-private_ or _package-protected_. ------------- PR: https://git.openjdk.org/jdk/pull/10070 From jjg at openjdk.org Mon Aug 29 23:34:44 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Mon, 29 Aug 2022 23:34:44 GMT Subject: RFR: 8292892: Javadoc index descriptions are not deterministic In-Reply-To: References: Message-ID: On Mon, 29 Aug 2022 21:03:34 GMT, John Neffenger wrote: > Please review these changes to the Javadoc index builders. This pull request adds 423 missing entries to the index of the JDK API Specification, corrects their package names in the member search index, and makes their descriptions deterministic. I'll follow up with more information in a separate comment. Excellent analysis and write up. (Just) for the record, I will note there is potentially another case that could be tested, where the element with package access is not exposed until a couple of subtypes down, as compared to being exposed in a direct subtype. That would stress the use of `containingType` in the code. But the general policy of using and documenting these somewhat hidden elements is all a bit ugly anyway, and I don't know that this extra case appears in JDK. test/langtools/jdk/javadoc/doclet/testIndexInherited/TestIndexInherited.java line 111: > 109: public static void main(String... args) throws Exception { > 110: TestIndexInherited tester = new TestIndexInherited(); > 111: tester.runTests(m -> new Object[]{Path.of(m.getName())}); These days, you can simplify this down to just `tester.runTests();`. The implication of the method will check the signature of the test methods and provide the appropriate path automatically. test/langtools/jdk/javadoc/doclet/testIndexInherited/TestIndexInherited.java line 154: > 152: public void testSuperclass(Path base) { > 153: String dir = base.resolve("out").toString(); > 154: javadoc("-d", dir, "-sourcepath", testSrc, "-private", "pkg1", "pkg2"); At first glance, the use of the `-private` option does not seem to match the method name `testSuperclass` or its matching description (tests entries in the superclass). There are two characteristics here that seem to be getting mixed up: 1. testing subclasses and superclasses 2. testing with default access (document public and protected) and with "more" access, such as using `-package` or `-private` options. Ideally, the tests should test subclasses and superclasses with default access, and then repeat, testing subclasses and superclasses with "more" access, such as with `-private`. test/langtools/jdk/javadoc/doclet/testIndexInherited/pkg1/ClassA.java line 1: > 1: /* It's not wrong to use separate files, as you have for `ClassA`, `ClassB` and `ClassC` but generally the prevailing style these days is to generate small test files (like these) from text blocks in the main test file. This makes it easier to see the sources all together, and avoids the overhead of the legal block. That being said, The amount of text after the legal block puts these in the gray area where either style is OK. ------------- PR: https://git.openjdk.org/jdk/pull/10070 From jjg at openjdk.org Mon Aug 29 23:46:11 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Mon, 29 Aug 2022 23:46:11 GMT Subject: RFR: 8292892: Javadoc index descriptions are not deterministic In-Reply-To: References: Message-ID: <80ogxbgejZAkrRsrNOHRVUsp96Ui5nABIe7SrfVPDqI=.64e9dd8c-302d-4ae8-b35e-22b6306e30b6@github.com> On Mon, 29 Aug 2022 21:03:34 GMT, John Neffenger wrote: > Please review these changes to the Javadoc index builders. This pull request adds 423 missing entries to the index of the JDK API Specification, corrects their package names in the member search index, and makes their descriptions deterministic. I'll follow up with more information in a separate comment. _?The sins of the father are to be laid upon the children.?_ I see this arises from `ZipConstants`, authored in JDK 1.1, before the availability of `import static` in JDK 5 onwards. Early on, the use was eventually seen as something of an anti-pattern, with unappreciated implications for compatibility, meaning that once in the API, it is hard to remove them. While the approach in this PR is probably correct and for the best, it is depressing to see the exact same constants being defined multiple times in the documentation. ------------- PR: https://git.openjdk.org/jdk/pull/10070 From darcy at openjdk.org Tue Aug 30 00:12:33 2022 From: darcy at openjdk.org (Joe Darcy) Date: Tue, 30 Aug 2022 00:12:33 GMT Subject: RFR: JDK-8173605: Remove support for source and target 1.7 option in javac Message-ID: Update to remove support for -source/-target/--release 7 from javac. As seen in the PR, many test fails are affected. Further refactorings of javac's implementation that can be made from dropping 7 support are left as future work. ------------- Commit messages: - Small refactoring to remove more stale code. - Remove effectively dead code. - Adjust data for CheckExamples test. - Partial restore of DEFAULT_METHODS Source.Feature for test java/lang/invoke/defineHiddenClass/PreviewHiddenClass.java. - Merge branch 'master' into JDK-8173605 - Fix MultiReleaseJars.java. - Test fixes. - Clean langtools test run. - CheckExamples passes. - Type annotations. - ... and 13 more: https://git.openjdk.org/jdk/compare/76ee5495...f3095350 Changes: https://git.openjdk.org/jdk/pull/10074/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=10074&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8173605 Stats: 4514 lines in 156 files changed: 25 ins; 4362 del; 127 mod Patch: https://git.openjdk.org/jdk/pull/10074.diff Fetch: git fetch https://git.openjdk.org/jdk pull/10074/head:pull/10074 PR: https://git.openjdk.org/jdk/pull/10074 From darcy at openjdk.org Tue Aug 30 00:20:09 2022 From: darcy at openjdk.org (Joe Darcy) Date: Tue, 30 Aug 2022 00:20:09 GMT Subject: RFR: JDK-8173605: Remove support for source and target 1.7 option in javac In-Reply-To: References: Message-ID: On Tue, 30 Aug 2022 00:04:03 GMT, Joe Darcy wrote: > Update to remove support for -source/-target/--release 7 from javac. > > As seen in the PR, many test fails are affected. Further refactorings of javac's implementation that can be made from dropping 7 support are left as future work. Please also review the accompanying CSR: https://bugs.openjdk.org/browse/JDK-8293047 Note that the DEFAULT_METHODS enum constant is used indirectly by a test to force a class file's minor version bits to be set as if a preview feature were used. If some other idiom is available, the DEFAULT_METHOD constant could be removed. Tier 1 and tier 2 test results were clean with this changes. ------------- PR: https://git.openjdk.org/jdk/pull/10074 From darcy at openjdk.org Tue Aug 30 01:05:23 2022 From: darcy at openjdk.org (Joe Darcy) Date: Tue, 30 Aug 2022 01:05:23 GMT Subject: RFR: JDK-8173605: Remove support for source and target 1.7 option in javac In-Reply-To: References: Message-ID: <7caOzUK-O_rtHE24lEnLDODLPj_gvixrSSFI-Is5zS0=.78f37a82-868c-4719-9145-cb2bd8df0588@github.com> On Tue, 30 Aug 2022 00:16:09 GMT, Joe Darcy wrote: > Please also review the accompanying CSR: > > https://bugs.openjdk.org/browse/JDK-8293047 > > Note that the DEFAULT_METHODS enum constant is used indirectly by a test to force a class file's minor version bits to be set as if a preview feature were used. If some other idiom is available, the DEFAULT_METHOD constant could be removed. > > Tier 1 and tier 2 test results were clean with this changes. PS I'll run a copyright update script before any push. ------------- PR: https://git.openjdk.org/jdk/pull/10074 From alanb at openjdk.org Tue Aug 30 06:29:52 2022 From: alanb at openjdk.org (Alan Bateman) Date: Tue, 30 Aug 2022 06:29:52 GMT Subject: RFR: JDK-8173605: Remove support for source and target 1.7 option in javac In-Reply-To: References: Message-ID: On Tue, 30 Aug 2022 00:04:03 GMT, Joe Darcy wrote: > Update to remove support for -source/-target/--release 7 from javac. > > As seen in the PR, many test fails are affected. Further refactorings of javac's implementation that can be made from dropping 7 support are left as future work. test/jdk/java/lang/reflect/OldenCompilingWithDefaults.java line 28: > 26: * @bug 8009267 > 27: * @summary Verify uses of isAnnotationPresent compile under older source versions > 28: * @compile OldenCompilingWithDefaults.java I skimmed through the description of JDK-8009267 and I'm wondering if this test is of any value now. ------------- PR: https://git.openjdk.org/jdk/pull/10074 From darcy at openjdk.org Tue Aug 30 21:59:10 2022 From: darcy at openjdk.org (Joe Darcy) Date: Tue, 30 Aug 2022 21:59:10 GMT Subject: RFR: JDK-8173605: Remove support for source and target 1.7 option in javac In-Reply-To: References: Message-ID: On Tue, 30 Aug 2022 06:26:25 GMT, Alan Bateman wrote: >> Update to remove support for -source/-target/--release 7 from javac. >> >> As seen in the PR, many test fails are affected. Further refactorings of javac's implementation that can be made from dropping 7 support are left as future work. > > test/jdk/java/lang/reflect/OldenCompilingWithDefaults.java line 28: > >> 26: * @bug 8009267 >> 27: * @summary Verify uses of isAnnotationPresent compile under older source versions >> 28: * @compile OldenCompilingWithDefaults.java > > I skimmed through the description of JDK-8009267 and I'm wondering if this test is of any value now. Certainly less useful than it once was! I can remove it in the next push. ------------- PR: https://git.openjdk.org/jdk/pull/10074 From vromero at openjdk.org Wed Aug 31 17:17:07 2022 From: vromero at openjdk.org (Vicente Romero) Date: Wed, 31 Aug 2022 17:17:07 GMT Subject: RFR: JDK-8173605: Remove support for source and target 1.7 option in javac In-Reply-To: References: Message-ID: On Tue, 30 Aug 2022 00:04:03 GMT, Joe Darcy wrote: > Update to remove support for -source/-target/--release 7 from javac. > > As seen in the PR, many test fails are affected. Further refactorings of javac's implementation that can be made from dropping 7 support are left as future work. looks good to me the PR looks good to me. You have mentioned that further refactorings could be done later on, I agree but you are already removing a lot of code, although that could have been forced to make some tests pass. I would recommend removing some support for 7 at `com.sun.tools.javac.comp.Infer` particularly the one guarded by `allowGraphInference`. I can also help with that later on if you prefer. If so please assign a follow-up for this issue to myself ------------- Marked as reviewed by vromero (Reviewer). PR: https://git.openjdk.org/jdk/pull/10074 From darcy at openjdk.org Wed Aug 31 17:25:09 2022 From: darcy at openjdk.org (Joe Darcy) Date: Wed, 31 Aug 2022 17:25:09 GMT Subject: RFR: JDK-8173605: Remove support for source and target 1.7 option in javac In-Reply-To: References: Message-ID: On Wed, 31 Aug 2022 17:13:04 GMT, Vicente Romero wrote: > the PR looks good to me. You have mentioned that further refactorings could be done later on, I agree but you are already removing a lot of code, although that could have been forced to make some tests pass. I would recommend removing some support for 7 at `com.sun.tools.javac.comp.Infer` particularly the one guarded by `allowGraphInference`. I can also help with that later on if you prefer. If so please assign a follow-up for this issue to myself Thanks Vicente; I assigned JDK-8293051: Further refactor javac after removal of -source/-target/--release 7 to you. ------------- PR: https://git.openjdk.org/jdk/pull/10074 From jjg at openjdk.org Wed Aug 31 18:18:36 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Wed, 31 Aug 2022 18:18:36 GMT Subject: RFR: JDK-8293178: Remove obsolete properties from javadoc resource file Message-ID: Please review a trivial update to remove some obsolete properties from a javadoc resource file. ------------- Commit messages: - JDK-8293178: Remove obsolete properties from javadoc resource file Changes: https://git.openjdk.org/jdk/pull/10105/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=10105&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8293178 Stats: 10 lines in 2 files changed: 0 ins; 6 del; 4 mod Patch: https://git.openjdk.org/jdk/pull/10105.diff Fetch: git fetch https://git.openjdk.org/jdk pull/10105/head:pull/10105 PR: https://git.openjdk.org/jdk/pull/10105 From prappo at openjdk.org Wed Aug 31 20:59:08 2022 From: prappo at openjdk.org (Pavel Rappo) Date: Wed, 31 Aug 2022 20:59:08 GMT Subject: RFR: JDK-8293178: Remove obsolete properties from javadoc resource file In-Reply-To: References: Message-ID: On Wed, 31 Aug 2022 18:11:09 GMT, Jonathan Gibbons wrote: > Please review a trivial update to remove some obsolete properties from a javadoc resource file. Marked as reviewed by prappo (Reviewer). ------------- PR: https://git.openjdk.org/jdk/pull/10105 From jjg at openjdk.org Wed Aug 31 22:16:12 2022 From: jjg at openjdk.org (Jonathan Gibbons) Date: Wed, 31 Aug 2022 22:16:12 GMT Subject: Integrated: JDK-8293178: Remove obsolete properties from javadoc resource file In-Reply-To: References: Message-ID: On Wed, 31 Aug 2022 18:11:09 GMT, Jonathan Gibbons wrote: > Please review a trivial update to remove some obsolete properties from a javadoc resource file. This pull request has now been integrated. Changeset: 6f297346 Author: Jonathan Gibbons URL: https://git.openjdk.org/jdk/commit/6f297346dc34f58d10c64a7bbe4e0f5b52ed33e3 Stats: 10 lines in 2 files changed: 0 ins; 6 del; 4 mod 8293178: Remove obsolete properties from javadoc resource file Reviewed-by: prappo ------------- PR: https://git.openjdk.org/jdk/pull/10105