From iris at openjdk.java.net Tue May 3 00:13:22 2022 From: iris at openjdk.java.net (Iris Clark) Date: Tue, 3 May 2022 00:13:22 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class In-Reply-To: References: Message-ID: <4kcClU0UAH2EX7p27W6t70Qpobw95vRF5a2eHg2WrN4=.1c7da657-a552-40c7-b7d7-14dd6e77d0ec@github.com> On Fri, 29 Apr 2022 00:29:50 GMT, Jonathan Gibbons wrote: > Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" > > The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. Marked as reviewed by iris (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From prappo at openjdk.java.net Tue May 3 12:19:33 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Tue, 3 May 2022 12:19:33 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class In-Reply-To: References: Message-ID: On Fri, 29 Apr 2022 00:29:50 GMT, Jonathan Gibbons wrote: > Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" > > The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. It's nice to see many `break` go. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 737: > 735: private Element getEnclosingPackageOrClass(Element e) { > 736: while (e != null) { > 737: if (e.getKind().isDeclaredType() || e.getKind() == ElementKind.PACKAGE) { This change does not seem to be equivalent: `isDeclaredType()` accepts more kinds than the `switch` did. Does it matter here? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 866: > 864: if (paramElement == null) { > 865: switch (env.currElement.getKind()) { > 866: case CLASS, ENUM, INTERFACE, ANNOTATION_TYPE -> { Neither an enum nor annotation can be generic. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1127: > 1125: return false; > 1126: > 1127: return switch (e.getKind()) { While uniformity of constructs is good, to me, the previous variant read better. Does this have to be a switch expression? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1171: > 1169: > 1170: private boolean isDefaultConstructor() { > 1171: return switch (env.currElement.getKind()) { Similar to the above. ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From prappo at openjdk.java.net Tue May 3 13:56:14 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Tue, 3 May 2022 13:56:14 GMT Subject: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) In-Reply-To: References: Message-ID: On Thu, 28 Apr 2022 02:05:47 GMT, Jonathan Gibbons wrote: > 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. This is nice work. I haven't seen it in detail, but I'm plannig to do so later. What's the logistics here? There are two interrelated bugs: 6251738 and 8226279. Are you going to add an 8226279 as an issue to this PR (`/issue add 8226279`)? What about @bug tags in tests? Are they going to mention both issues? src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java line 290: > 288: R visitSince(SinceTree node, P p); > 289: > 290: /** This file uses a consistent style for doc comments for `visit` methods. Consider adhering to that style for the time being. If you think that the style could be improved, it should be improved in a separate PR. src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 340: > 338: SnippetTree newSnippetTree(List attributes, TextTree text); > 339: > 340: /** Similar comment to that of DocTreeVisitor: consider adhering to the file style. src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 512: > 510: } > 511: > 512: /** Similar comment on the file style. src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 532: > 530: > 531: /** > 532: * {@inheritDoc} This implementation scans the children in left to right order. Same as above: surprising. src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 544: > 542: > 543: /** > 544: * {@inheritDoc} This implementation scans the children in left to right order. This change is surprising; firstly, it's unrelated to this PR, secondly... why? src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java line 466: > 464: } > 465: > 466: /** Again: the file style. src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java line 1217: > 1215: @Override > 1216: public boolean isBlank() { > 1217: return text.isBlank(); Can text be null? src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java line 419: > 417: > 418: @Override @DefinedBy(Api.COMPILER_TREE) > 419: public DCSpec newSpecTree(TextTree url, List title) { In DocTreeFactory the first parameter is called uri. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ExternalSpecsWriter.java line 68: > 66: * Generates the file with the summary of all the references to external specifications. > 67: * > 68: *

This is NOT part of any supported API. We abolished such notes in JDK-8284362. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java line 33: > 31: import java.nio.file.InvalidPathException; > 32: import java.nio.file.Path; > 33: import java.util.ArrayList; This does not seem necessary for this PR and looks like an artifact of editing in an IDE. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SpecTaglet.java line 44: > 42: * A taglet that represents the {@code @spec} tag. > 43: * > 44: *

This is NOT part of any supported API. See my comment on such notes above. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SpecTaglet.java line 49: > 47: * deletion without notice. > 48: */ > 49: public class SpecTaglet extends BaseTaglet implements InheritableTaglet { Ooh! This taglet is inheritable. Is it the right thing to do? If the inheritance is not needed down the hierarchy, how can the author avoid it? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java line 192: > 190: * > 191: * @param element the element that owns the doc comment > 192: * @param specTags the array of @spec tags. Naked tags that aren't meant to be interpreted by javadoc make me uncomfortable. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java line 277: > 275: > 276: private static boolean isNonEmpty(List list) { > 277: return list != null && !list.isEmpty(); `output.inlineTags` should never be null. Separately, can this readability change be done in a separate PR? I do have one suitable PR in the works, which can include it. test/langtools/jdk/javadoc/doclet/testConditionalPages/TestConditionalPages.java line 2: > 1: /* > 2: * Copyright (c) 2020, 2022, Oracle and/or its affiliates. All rights reserved. Consider adding 6251738 to `@bug`. test/langtools/jdk/javadoc/doclet/testMetadata/TestMetadata.java line 2: > 1: /* > 2: * Copyright (c) 2019, 2022, Oracle and/or its affiliates. All rights reserved. Same as above. test/langtools/tools/javac/diags/examples/NoTitle.java line 2: > 1: /* > 2: * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved. It's surprising to see 2012 here. test/langtools/tools/javac/diags/examples/NoURI.java line 2: > 1: /* > 2: * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved. Same as above. ------------- PR: https://git.openjdk.java.net/jdk/pull/8439 From rriggs at openjdk.java.net Tue May 3 17:53:18 2022 From: rriggs at openjdk.java.net (Roger Riggs) Date: Tue, 3 May 2022 17:53:18 GMT Subject: RFR: 8283606: Tests may fail with zh locale on MacOS [v2] In-Reply-To: References: Message-ID: On Thu, 24 Mar 2022 17:30:22 GMT, Vikey Chen wrote: >> From the test doc of openjdk https://openjdk.java.net/groups/build/doc/testing.html >>> If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting LANG="en_US" in the environment before running tests should work. On Windows or MacOS, setting JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US" helps for most, but not all test cases. >> >> However, on MacOS 12.1, running `make test-tier1 JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"` command for tier-1 test, some tests still fail, including the following in tier-1.The tests expects output messages in English, but Chinese message are still produced. >> >> test/hotspot/jtreg/runtime/classFileParserBug/TestEmptyBootstrapMethodsAttr.java >> test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java >> test/langtools/jdk/javadoc/tool/6964914/TestUserDoclet.java >> test/langtools/jdk/javadoc/tool/EnsureNewOldDoclet.java >> test/langtools/jdk/javadoc/tool/testLocaleOption/TestLocaleOption.java >> test/langtools/tools/javac/T8132562/ClassPathWithDoubleQuotesTest.java >> test/langtools/tools/javac/options/smokeTests/OptionSmokeTest.java >> test/langtools/tools/javac/platform/PlatformProviderTest.java >> test/langtools/tools/jdeps/MultiReleaseJar.java > > Vikey Chen has updated the pull request incrementally with one additional commit since the last revision: > > polish Looks fine. ------------- Marked as reviewed by rriggs (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/7924 From prappo at openjdk.java.net Tue May 3 19:30:01 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Tue, 3 May 2022 19:30:01 GMT Subject: RFR: 8285470: Improve handling of @inheritDoc [v4] In-Reply-To: References: Message-ID: <4jQYWLpp7Uf8aWk2MWlWDycFAqro2sY_ruE2JlAl6ww=.e928c7df-fa16-4146-b9dc-671dec6e4e0b@github.com> > The only taglet that along with its own tag needs to know the immediately enclosing tag is `InheritDocTaglet`: > > @return {@inheritDoc} > @throws NullPointerException {@inheritDoc} > @param p {@inheritDoc} > > However, the immediately enclosing tag is unconditionally passed to all taglets. If we stop passing it and make `InheritDocTaglet` compute it instead, the code becomes cleaner. > > While reviewing, particularly note these benefits of the proposed change: > > * taglet-handling code knows less about `@inheritDoc`, and > * `InheritDocTaglet` receives its own tag, not the tag that encloses it Pavel Rappo 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 ten additional commits since the last revision: - Merge branch 'master' into 8285470 - (feedback) typography - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java Co-authored-by: ExE Boss <3889017+ExE-Boss at users.noreply.github.com> - (fix) Fix a test failure Fixes a failure in jdk/javadoc/doclet/testInheritDocWithinInappropriateTag/TestInheritDocWithinInappropriateTag.java - (cleanup) Simplify retrieveInheritedDocumentation - (cleanup) Clarify retrieveInheritedDocumentation - (cleanup) Unify specs of commentTagsToContent - Stop passing "holderTag" - (cleanup) Remove useless null check DocFinder.search cannot return null. ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/8361/files - new: https://git.openjdk.java.net/jdk/pull/8361/files/8bf226f7..31721e9d Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=8361&range=03 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=8361&range=02-03 Stats: 27873 lines in 776 files changed: 19631 ins; 3824 del; 4418 mod Patch: https://git.openjdk.java.net/jdk/pull/8361.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8361/head:pull/8361 PR: https://git.openjdk.java.net/jdk/pull/8361 From jjg at openjdk.java.net Tue May 3 20:47:33 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 20:47:33 GMT Subject: RFR: JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section Message-ID: As described in the JBS issue, the observed problem is a side-effect of a related but different issue, which is that record classes are not treated the same was as enum classes when it comes to generating the class hierarchy in `ClassTree`. Because record classes are not treated specially/differently, they are treated as ordinary/plain classes, with the side-effect that the page for `java.lang.Record` shows `Direct Known Subclasses`. The underlying fix is therefore to clone the enum support in `ClassTree` and related classes, to provide support for record classes. It is possible to do an extreme minimal clone, but that just clones some of the messy evolution already there. Instead, the code in `ClassTree` and its clients is refactored and modernized. Previously there were four explicit pairs of member fields, containing data for different groups (hierarchies) of classes, namely: plain classes, enum classes, interfaces and annotation interfaces. These fields are most of the code to support them are moved into some new abstractions to encapsulate related functionality. 1. The main new abstraction in `ClassTree` is `Hierarchy` which provides the support for the different hierarchies displayed in the generated pages. 2. A new enum `HierarchyKind` identifies the four existing hierarchies (listed above) and now a new one, for record classes. The hierarchies correspond to the different kinds of declared type. 3. A small new class `SubtypeMap` which is a multi-map for mapping a type element to its subtypes. This is used in `Hierarchy` and to record the classes that implement an interfaces. Generally, the naming should be clearer and more obvious. The most confusing name in the old code was `enumSubtypes` which was weird because enum classes don't have subtypes. It meant "subtypes of supertypes of enum classes". This was a prime motivator to switch to the `hierarchy` terminology. The variant spellings of `intfacs` have all been replaced by `interfaces`, and `classtree` becomes `classTree`. *Testing*: a new test case has been added to the `TestRecordTypes.java` test, which verifies the new record hierarchy is displayed on a a package tree page. It is not simple to directly test the observed/reported behavior, because it is specific to the JDK API documentation, and because it is about the content of the `java.lang.Record` API page. However, manual inspection and diff comparison between JDK API documentation generated before and after this change reveals only expected differences. These differences are on the `java.lang.R4cord` page (where the offending section is no longer displayed) and on the pages related to the two existing records in JDK ... which are now listed in `Record Class Hierarchy` sections in the appropriate `package-tree.html` files. ------------- Commit messages: - fix copyright; update test description - JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section Changes: https://git.openjdk.java.net/jdk/pull/8523/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8523&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8285939 Stats: 440 lines in 11 files changed: 141 ins; 131 del; 168 mod Patch: https://git.openjdk.java.net/jdk/pull/8523.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8523/head:pull/8523 PR: https://git.openjdk.java.net/jdk/pull/8523 From jjg at openjdk.java.net Tue May 3 21:29:19 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 21:29:19 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class In-Reply-To: References: Message-ID: On Tue, 3 May 2022 11:31:09 GMT, Pavel Rappo wrote: >> Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 866: > >> 864: if (paramElement == null) { >> 865: switch (env.currElement.getKind()) { >> 866: case CLASS, ENUM, INTERFACE, ANNOTATION_TYPE -> { > > Neither an enum nor annotation can be generic. good point > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1127: > >> 1125: return false; >> 1126: >> 1127: return switch (e.getKind()) { > > While uniformity of constructs is good, to me, the previous variant read better. Does this have to be a switch expression? no. it may work better as a simple (non-switch) expression; i'll try it > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1171: > >> 1169: >> 1170: private boolean isDefaultConstructor() { >> 1171: return switch (env.currElement.getKind()) { > > Similar to the above. similar answer ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Tue May 3 21:34:17 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 21:34:17 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class In-Reply-To: References: Message-ID: On Tue, 3 May 2022 11:03:02 GMT, Pavel Rappo wrote: >> Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 737: > >> 735: private Element getEnclosingPackageOrClass(Element e) { >> 736: while (e != null) { >> 737: if (e.getKind().isDeclaredType() || e.getKind() == ElementKind.PACKAGE) { > > This change does not seem to be equivalent: `isDeclaredType()` accepts more kinds than the `switch` did. Does it matter here? I don't think it matters and/or the code is more correct according to the semantics of the name. I think this is a case where we get bit-rot from new values being added to enums and not being consistently used throughout the code. ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Tue May 3 21:53:21 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 21:53:21 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2] In-Reply-To: References: Message-ID: > Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" > > The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/8460/files - new: https://git.openjdk.java.net/jdk/pull/8460/files/d18824b8..edbb9247 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=8460&range=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=8460&range=00-01 Stats: 23 lines in 1 file changed: 3 ins; 9 del; 11 mod Patch: https://git.openjdk.java.net/jdk/pull/8460.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8460/head:pull/8460 PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Tue May 3 21:58:07 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 21:58:07 GMT Subject: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) In-Reply-To: References: Message-ID: On Tue, 3 May 2022 12:38:09 GMT, Pavel Rappo wrote: >> 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. > > src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java line 290: > >> 288: R visitSince(SinceTree node, P p); >> 289: >> 290: /** > > This file uses a consistent style for doc comments for `visit` methods. Consider adhering to that style for the time being. If you think that the style could be improved, it should be improved in a separate PR. The style is consistent with other recent additions that have default methods. In other words, there is not one but two styles already in play in this file, for the two different kinds of methods. ------------- PR: https://git.openjdk.java.net/jdk/pull/8439 From jjg at openjdk.java.net Tue May 3 22:02:24 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 22:02:24 GMT Subject: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) In-Reply-To: References: Message-ID: On Tue, 3 May 2022 12:40:42 GMT, Pavel Rappo wrote: >> 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. > > src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 340: > >> 338: SnippetTree newSnippetTree(List attributes, TextTree text); >> 339: >> 340: /** > > Similar comment to that of DocTreeVisitor: consider adhering to the file style. I see there is a missing `@since` tag, which I'll fix. I'd prefer to leave the extra whitespace for now, and maybe cleanup the style of the other comments later. > src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 512: > >> 510: } >> 511: >> 512: /** > > Similar comment on the file style. I'll adjust the order of the tags. Aside: we should have a guideline somewhere on the recommended order of block tags in a comment, ------------- PR: https://git.openjdk.java.net/jdk/pull/8439 From jjg at openjdk.java.net Tue May 3 22:11:42 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 22:11:42 GMT Subject: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) In-Reply-To: References: Message-ID: On Tue, 3 May 2022 12:42:41 GMT, Pavel Rappo wrote: >> 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. > > src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 544: > >> 542: >> 543: /** >> 544: * {@inheritDoc} This implementation scans the children in left to right order. > > This change is surprising; firstly, it's unrelated to this PR, secondly... why? Bug and/or some variant of cut n paste. I'll ensure to use `@implSpec`. ------------- PR: https://git.openjdk.java.net/jdk/pull/8439 From prappo at openjdk.java.net Tue May 3 22:28:34 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Tue, 3 May 2022 22:28:34 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2] In-Reply-To: References: Message-ID: On Tue, 3 May 2022 21:53:21 GMT, Jonathan Gibbons wrote: >> Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. > > Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: > > address review feedback I have a few more comments, Jon. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 217: > 215: hasNonWhitespaceText = false; > 216: > 217: implicitHeadingRank = switch (p.getLeaf().getKind()) { (observation) Since _rank_ is a rather unusual word to see, I explored this a bit. Numerals in H1, H2, H3, H4, H5, and H6 were somewhat implicitly referred to as _heading levels_ by HTML4, and indeed became referred to as _ranks_ in HTML5. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 866: > 864: if (paramElement == null) { > 865: switch (env.currElement.getKind()) { > 866: case CLASS, INTERFACE -> { A record can be generic too. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1230: > 1228: for (DocTree d: list) { > 1229: switch (d.getKind()) { > 1230: case TEXT -> { Using `switch` here seems overkill. ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Tue May 3 22:28:36 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 22:28:36 GMT Subject: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) In-Reply-To: References: Message-ID: On Tue, 3 May 2022 13:23:41 GMT, Pavel Rappo wrote: >> 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. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java line 277: > >> 275: >> 276: private static boolean isNonEmpty(List list) { >> 277: return list != null && !list.isEmpty(); > > `output.inlineTags` should never be null. Separately, can this readability change be done in a separate PR? I do have one suitable PR in the works, which can include it. I'll back out these lines as long as the tests still pass. > test/langtools/jdk/javadoc/doclet/testConditionalPages/TestConditionalPages.java line 2: > >> 1: /* >> 2: * Copyright (c) 2020, 2022, Oracle and/or its affiliates. All rights reserved. > > Consider adding 6251738 to `@bug`. Mmmm, OK ------------- PR: https://git.openjdk.java.net/jdk/pull/8439 From prappo at openjdk.java.net Tue May 3 22:40:56 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Tue, 3 May 2022 22:40:56 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2] In-Reply-To: References: Message-ID: On Tue, 3 May 2022 21:53:21 GMT, Jonathan Gibbons wrote: >> Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. > > Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: > > address review feedback Marked as reviewed by prappo (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Tue May 3 22:41:00 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 22:41:00 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2] In-Reply-To: References: Message-ID: On Tue, 3 May 2022 22:16:25 GMT, Pavel Rappo wrote: >> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: >> >> address review feedback > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 866: > >> 864: if (paramElement == null) { >> 865: switch (env.currElement.getKind()) { >> 866: case CLASS, INTERFACE -> { > > A record can be generic too. Yes, but RECORD is handled in a different case, along with METHOD and CONSTRUCTOR, because it can have "plain" `@param` as well as type-parameter `@param`. In contrast, a class or interface can only have type-parameter `@param` and never plain `@param`. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1230: > >> 1228: for (DocTree d: list) { >> 1229: switch (d.getKind()) { >> 1230: case TEXT -> { > > Using `switch` here seems overkill. I almost fixed that one earlier. OK, I'll do that too. It was over-zealous use of use of unqualified names in an enum-switch ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From prappo at openjdk.java.net Tue May 3 22:41:01 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Tue, 3 May 2022 22:41:01 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2] In-Reply-To: References: Message-ID: On Tue, 3 May 2022 22:30:51 GMT, Jonathan Gibbons wrote: > Yes, but RECORD is handled in a different case, along with METHOD and CONSTRUCTOR, because it can have "plain" `@param` as well as type-parameter `@param`. In contrast, a class or interface can only have type-parameter `@param` and never plain `@param`. You are correct; I missed that unconditionality in that second arm for`METHOD, CONSTRUCTOR, RECORD`. ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Tue May 3 22:47:49 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 22:47:49 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v3] In-Reply-To: References: Message-ID: <8LZE068FcdMqAk4tMZkTlmCbc62rdG533ieO8LqTYoA=.b960f449-31d4-4080-bf40-dd9721598a92@github.com> > Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" > > The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/8460/files - new: https://git.openjdk.java.net/jdk/pull/8460/files/edbb9247..7be7ab30 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=8460&range=02 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=8460&range=01-02 Stats: 9 lines in 1 file changed: 0 ins; 6 del; 3 mod Patch: https://git.openjdk.java.net/jdk/pull/8460.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8460/head:pull/8460 PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Tue May 3 22:47:51 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 3 May 2022 22:47:51 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v2] In-Reply-To: References: Message-ID: On Tue, 3 May 2022 22:06:29 GMT, Pavel Rappo wrote: >> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: >> >> address review feedback > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 217: > >> 215: hasNonWhitespaceText = false; >> 216: >> 217: implicitHeadingRank = switch (p.getLeaf().getKind()) { > > (observation) Since _rank_ is a rather unusual word to see, I explored this a bit. Numerals in H1, H2, H3, H4, H5, and H6 were somewhat implicitly referred to as _heading levels_ by HTML4, and indeed became referred to as _ranks_ in HTML5. yes, that is where I found the term. ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From prappo at openjdk.java.net Wed May 4 15:02:26 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Wed, 4 May 2022 15:02:26 GMT Subject: RFR: JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section In-Reply-To: References: Message-ID: <2z6_jfoyWawPxOoYrwc4k8RPZRKLm8t8OZzQyjqTTZk=.1fda2322-e364-4468-b8cf-b4b6ef52f060@github.com> On Tue, 3 May 2022 20:38:44 GMT, Jonathan Gibbons wrote: > As described in the JBS issue, the observed problem is a side-effect of a related but different issue, which is that record classes are not treated the same was as enum classes when it comes to generating the class hierarchy in `ClassTree`. Because record classes are not treated specially/differently, they are treated as ordinary/plain classes, with the side-effect that the page for `java.lang.Record` shows `Direct Known Subclasses`. > > The underlying fix is therefore to clone the enum support in `ClassTree` and related classes, to provide support for record classes. It is possible to do an extreme minimal clone, but that just clones some of the messy evolution already there. Instead, the code in `ClassTree` and its clients is refactored and modernized. > > Previously there were four explicit pairs of member fields, containing data for different groups (hierarchies) of classes, namely: plain classes, enum classes, interfaces and annotation interfaces. These fields are most of the code to support them are moved into some new abstractions to encapsulate related functionality. > > 1. The main new abstraction in `ClassTree` is `Hierarchy` which provides the support for the different hierarchies displayed in the generated pages. > 2. A new enum `HierarchyKind` identifies the four existing hierarchies (listed above) and now a new one, for record classes. The hierarchies correspond to the different kinds of declared type. > 3. A small new class `SubtypeMap` which is a multi-map for mapping a type element to its subtypes. This is used in `Hierarchy` and to record the classes that implement an interfaces. > > Generally, the naming should be clearer and more obvious. The most confusing name in the old code was `enumSubtypes` which was weird because enum classes don't have subtypes. It meant "subtypes of supertypes of enum classes". This was a prime motivator to switch to the `hierarchy` terminology. The variant spellings of `intfacs` have all been replaced by `interfaces`, and `classtree` becomes `classTree`. > > *Testing*: a new test case has been added to the `TestRecordTypes.java` test, which verifies the new record hierarchy is displayed on a a package tree page. It is not simple to directly test the observed/reported behavior, because it is specific to the JDK API documentation, and because it is about the content of the `java.lang.Record` API page. However, manual inspection and diff comparison between JDK API documentation generated before and after this change reveals only expected differences. These differences are on the `java.lang.R4cord` page (where the offending section is no longer displayed) and on the pages related to the two existing records in JDK ... which are now listed in `Record Class Hierarchy` sections in the appropriate `package-tree.html` files. Although I haven't looked into code in detail, I can confirm that the following JDK API pages have been updated and look good: 1. java.base/java/lang/Record.html 2. java.base/java/lang/class-use/Object.html 3. java.base/java/lang/class-use/Record.html 4. java.base/java/lang/package-use.html 5. jdk.jshell/jdk/jshell/package-tree.html 6. jdk.net/jdk/net/package-tree.html 7. overview-tree.html WRT documentation, a hierarchy of records now behave similarly to that of enums. ------------- PR: https://git.openjdk.java.net/jdk/pull/8523 From prappo at openjdk.java.net Wed May 4 18:34:25 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Wed, 4 May 2022 18:34:25 GMT Subject: RFR: JDK-8285869: Selective cleanup in doclint Checker class [v3] In-Reply-To: <8LZE068FcdMqAk4tMZkTlmCbc62rdG533ieO8LqTYoA=.b960f449-31d4-4080-bf40-dd9721598a92@github.com> References: <8LZE068FcdMqAk4tMZkTlmCbc62rdG533ieO8LqTYoA=.b960f449-31d4-4080-bf40-dd9721598a92@github.com> Message-ID: On Tue, 3 May 2022 22:47:49 GMT, Jonathan Gibbons wrote: >> Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" >> >> The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. > > Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: > > address review feedback Marked as reviewed by prappo (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Wed May 4 20:27:06 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Wed, 4 May 2022 20:27:06 GMT Subject: Integrated: JDK-8285869: Selective cleanup in doclint Checker class In-Reply-To: References: Message-ID: On Fri, 29 Apr 2022 00:29:50 GMT, Jonathan Gibbons wrote: > Please review some localized cleanup for the doclint Checker class, primarily focused on upgrading to the use of "enhanced `switch`" > > The output of one test was changed because of some improvements in one switch statement to eliminate the use of fall-through semantics. This pull request has now been integrated. Changeset: 28e6d805 Author: Jonathan Gibbons URL: https://git.openjdk.java.net/jdk/commit/28e6d805f4bc9d107ac839aca854bcb96a6637d8 Stats: 154 lines in 2 files changed: 12 ins; 51 del; 91 mod 8285869: Selective cleanup in doclint Checker class Reviewed-by: iris, prappo ------------- PR: https://git.openjdk.java.net/jdk/pull/8460 From jjg at openjdk.java.net Wed May 4 20:31:02 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Wed, 4 May 2022 20:31:02 GMT Subject: RFR: 8285470: Improve handling of @inheritDoc [v4] In-Reply-To: <4jQYWLpp7Uf8aWk2MWlWDycFAqro2sY_ruE2JlAl6ww=.e928c7df-fa16-4146-b9dc-671dec6e4e0b@github.com> References: <4jQYWLpp7Uf8aWk2MWlWDycFAqro2sY_ruE2JlAl6ww=.e928c7df-fa16-4146-b9dc-671dec6e4e0b@github.com> Message-ID: On Tue, 3 May 2022 19:30:01 GMT, Pavel Rappo wrote: >> The only taglet that along with its own tag needs to know the immediately enclosing tag is `InheritDocTaglet`: >> >> @return {@inheritDoc} >> @throws NullPointerException {@inheritDoc} >> @param p {@inheritDoc} >> >> However, the immediately enclosing tag is unconditionally passed to all taglets. If we stop passing it and make `InheritDocTaglet` compute it instead, the code becomes cleaner. >> >> While reviewing, particularly note these benefits of the proposed change: >> >> * taglet-handling code knows less about `@inheritDoc`, and >> * `InheritDocTaglet` receives its own tag, not the tag that encloses it > > Pavel Rappo 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 ten additional commits since the last revision: > > - Merge branch 'master' into 8285470 > - (feedback) typography > - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java > > Co-authored-by: ExE Boss <3889017+ExE-Boss at users.noreply.github.com> > - (fix) Fix a test failure > > Fixes a failure in jdk/javadoc/doclet/testInheritDocWithinInappropriateTag/TestInheritDocWithinInappropriateTag.java > - (cleanup) Simplify retrieveInheritedDocumentation > - (cleanup) Clarify retrieveInheritedDocumentation > - (cleanup) Unify specs of commentTagsToContent > - Stop passing "holderTag" > - (cleanup) Remove useless null check > > DocFinder.search cannot return null. OK. I still have reservations about excessive use of the tree-search methods, especially when the info is already available higher up the call stack. That being said, I agree that it is an improvement to not pass the `holder` down the stack, and this change did trigger an improvement to the tree-search support. If there are performance issues, we can either revert the use of `holder` or find some other way to pass the info down to the taglet, perhaps via the taglet writer (impl). ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/8361 From jjg at openjdk.java.net Wed May 4 20:36:57 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Wed, 4 May 2022 20:36:57 GMT Subject: RFR: JDK-8282559: Allow multiple search terms in javadoc search [v3] In-Reply-To: <2AWn6UB3IjF2gWcZ_Fuu9bn1V8zgVu0JyxecCmwUUPA=.39acddc4-0274-4c3c-bedf-d1d3691c1312@github.com> References: <2AWn6UB3IjF2gWcZ_Fuu9bn1V8zgVu0JyxecCmwUUPA=.39acddc4-0274-4c3c-bedf-d1d3691c1312@github.com> Message-ID: On Tue, 19 Apr 2022 12:45:18 GMT, Hannes Walln?fer wrote: >> Please review the first of two PRs to enhance JavaDoc search. >> >> This one focuses on the existing search script, to which it adds the feature to search for multiple terms. It also improves the implementation of case-sensitive search as well as rating of matches and provides some general update and refactoring of the script. >> >> The search section in the help page is updated to mention the multiple search term feature, and I repurposed the last example to show the new feature. >> >> The new search function can be tested here (top-level API doc files only): >> http://cr.openjdk.java.net/~hannesw/8282559/api.00/ > > Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision: > > Improve help text Approved, with a grammar suggestion. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 328: > 326: doclet.help.search.intro=You can search for definitions of modules, packages, types, fields, methods, \ > 327: system properties and other terms defined in the API. These items can be searched using part or all \ > 328: of the name, optionally using "camelCase" abbreviations or multiple search terms separated by whitespace. \ Suggest a comma between "abbreviations" and "or multiple search terms" ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/8185 From jjg at openjdk.java.net Wed May 4 20:51:17 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Wed, 4 May 2022 20:51:17 GMT Subject: RFR: JDK-8248863: Add search landing page to API documentation [v3] In-Reply-To: References: Message-ID: On Tue, 19 Apr 2022 21:04:04 GMT, Hannes Walln?fer wrote: >> This is the second of two PRs to enhance JavaDoc search, it is based on the first one (#8185). >> >> It adds a standalone search page (search.html) along with its own script file (search-page.js). This PR is very similar to the last prototype I uploaded and demoed, the changes are mostly tweaks to the markup, style sheets and text. >> >> JDK API docs rendered with this patch can be viewed and tested here (top-level files only, updated on April 20th): >> http://cr.openjdk.java.net/~hannesw/8248863/api.02/ >> http://cr.openjdk.java.net/~hannesw/8248863/api.02/search.html > > Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision: > > - Use different max results values for popup and page search > - Fix search link height OK. For the record, I note @hns gave us a walkthrough of the new JavaScript code,. One general result from that was a desire for more comments ... at a high-level for a description of the general search algorithm, at a medium level for some of the more interesting functions and occasionally down at the detail level, when the code is not obviously self-documenting, such as in the logic to build the regular expressions for the search. It would also help to note somewhere that the search is on a very specific dataset (the search index files generated by the doclet) and that we should document the format of those files somewhere. Finally, we discussed the idea to "partially minify" the JavaScript files, to strip out comments and unnecessary whitespace, so that there is no inhibition of the amount of comments that might be added and to reduce the download cost/time for end users. This processing could maybe be done in the makefiles at build time. Comments and minifying the file can be done in a followup PR. Great work. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/8226 From prappo at openjdk.java.net Wed May 4 20:58:25 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Wed, 4 May 2022 20:58:25 GMT Subject: RFR: 8285470: Improve handling of @inheritDoc [v4] In-Reply-To: <4jQYWLpp7Uf8aWk2MWlWDycFAqro2sY_ruE2JlAl6ww=.e928c7df-fa16-4146-b9dc-671dec6e4e0b@github.com> References: <4jQYWLpp7Uf8aWk2MWlWDycFAqro2sY_ruE2JlAl6ww=.e928c7df-fa16-4146-b9dc-671dec6e4e0b@github.com> Message-ID: <3xNkgSz-ieGw-xXQEmnN213z3KiMWBnPQ0OvhKV7tZM=.dc66af09-f9cb-464c-8483-a874f4540a72@github.com> On Tue, 3 May 2022 19:30:01 GMT, Pavel Rappo wrote: >> The only taglet that along with its own tag needs to know the immediately enclosing tag is `InheritDocTaglet`: >> >> @return {@inheritDoc} >> @throws NullPointerException {@inheritDoc} >> @param p {@inheritDoc} >> >> However, the immediately enclosing tag is unconditionally passed to all taglets. If we stop passing it and make `InheritDocTaglet` compute it instead, the code becomes cleaner. >> >> While reviewing, particularly note these benefits of the proposed change: >> >> * taglet-handling code knows less about `@inheritDoc`, and >> * `InheritDocTaglet` receives its own tag, not the tag that encloses it > > Pavel Rappo 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 ten additional commits since the last revision: > > - Merge branch 'master' into 8285470 > - (feedback) typography > - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java > > Co-authored-by: ExE Boss <3889017+ExE-Boss at users.noreply.github.com> > - (fix) Fix a test failure > > Fixes a failure in jdk/javadoc/doclet/testInheritDocWithinInappropriateTag/TestInheritDocWithinInappropriateTag.java > - (cleanup) Simplify retrieveInheritedDocumentation > - (cleanup) Clarify retrieveInheritedDocumentation > - (cleanup) Unify specs of commentTagsToContent > - Stop passing "holderTag" > - (cleanup) Remove useless null check > > DocFinder.search cannot return null. Thanks, Jon. For the reader's convenience, let me link to that tree-search support improvement that you mentioned: JDK-8267690 (https://github.com/openjdk/jdk/pull/8369) ------------- PR: https://git.openjdk.java.net/jdk/pull/8361 From prappo at openjdk.java.net Wed May 4 20:58:27 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Wed, 4 May 2022 20:58:27 GMT Subject: Integrated: 8285470: Improve handling of @inheritDoc In-Reply-To: References: Message-ID: <3SnP4KylJ1g3P46nOgCVB92kla_onH5L5iShpeterOI=.6be10691-306d-4d71-82d4-0ef4fc6a5c60@github.com> On Fri, 22 Apr 2022 14:05:44 GMT, Pavel Rappo wrote: > The only taglet that along with its own tag needs to know the immediately enclosing tag is `InheritDocTaglet`: > > @return {@inheritDoc} > @throws NullPointerException {@inheritDoc} > @param p {@inheritDoc} > > However, the immediately enclosing tag is unconditionally passed to all taglets. If we stop passing it and make `InheritDocTaglet` compute it instead, the code becomes cleaner. > > While reviewing, particularly note these benefits of the proposed change: > > * taglet-handling code knows less about `@inheritDoc`, and > * `InheritDocTaglet` receives its own tag, not the tag that encloses it This pull request has now been integrated. Changeset: bb022b24 Author: Pavel Rappo URL: https://git.openjdk.java.net/jdk/commit/bb022b24cfdad9d6826140c6b26c46f480e7457d Stats: 74 lines in 7 files changed: 5 ins; 26 del; 43 mod 8285470: Improve handling of @inheritDoc Reviewed-by: jjg ------------- PR: https://git.openjdk.java.net/jdk/pull/8361 From iklam at openjdk.java.net Thu May 5 00:09:28 2022 From: iklam at openjdk.java.net (Ioi Lam) Date: Thu, 5 May 2022 00:09:28 GMT Subject: RFR: 8283606: Tests may fail with zh locale on MacOS [v4] In-Reply-To: <21e-mJzcWAauSAEVbW0Icg2ELKkADKi1IgpcshgObfQ=.c65f5570-de08-444f-b6a4-e37509862267@github.com> References: <21e-mJzcWAauSAEVbW0Icg2ELKkADKi1IgpcshgObfQ=.c65f5570-de08-444f-b6a4-e37509862267@github.com> Message-ID: <1WS-PIPcRSnYI2AjzykxCMZhFLpyInWL1JGmMTZjhuY=.88e75659-952a-4313-837b-6770dbe994ca@github.com> On Mon, 28 Mar 2022 17:00:39 GMT, Vikey Chen wrote: >> From the test doc of openjdk https://openjdk.java.net/groups/build/doc/testing.html >>> If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting LANG="en_US" in the environment before running tests should work. On Windows or MacOS, setting JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US" helps for most, but not all test cases. >> >> However, on MacOS 12.1, running `make test-tier1 JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"` command for tier-1 test, some tests still fail, including the following in tier-1.The tests expects output messages in English, but Chinese message are still produced. >> >> test/hotspot/jtreg/runtime/classFileParserBug/TestEmptyBootstrapMethodsAttr.java >> test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java >> test/langtools/jdk/javadoc/tool/6964914/TestUserDoclet.java >> test/langtools/jdk/javadoc/tool/EnsureNewOldDoclet.java >> test/langtools/jdk/javadoc/tool/testLocaleOption/TestLocaleOption.java >> test/langtools/tools/javac/T8132562/ClassPathWithDoubleQuotesTest.java >> test/langtools/tools/javac/options/smokeTests/OptionSmokeTest.java >> test/langtools/tools/javac/platform/PlatformProviderTest.java >> test/langtools/tools/jdeps/MultiReleaseJar.java > > Vikey Chen has updated the pull request incrementally with one additional commit since the last revision: > > Locale.ENGLISH to Locale.US I tested the patch on latest JDK repo and passed tiers 1 and 2. ------------- PR: https://git.openjdk.java.net/jdk/pull/7924 From duke at openjdk.java.net Thu May 5 00:09:30 2022 From: duke at openjdk.java.net (Vikey Chen) Date: Thu, 5 May 2022 00:09:30 GMT Subject: Integrated: 8283606: Tests may fail with zh locale on MacOS In-Reply-To: References: Message-ID: On Wed, 23 Mar 2022 15:34:43 GMT, Vikey Chen wrote: > From the test doc of openjdk https://openjdk.java.net/groups/build/doc/testing.html >> If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting LANG="en_US" in the environment before running tests should work. On Windows or MacOS, setting JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US" helps for most, but not all test cases. > > However, on MacOS 12.1, running `make test-tier1 JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"` command for tier-1 test, some tests still fail, including the following in tier-1.The tests expects output messages in English, but Chinese message are still produced. > > test/hotspot/jtreg/runtime/classFileParserBug/TestEmptyBootstrapMethodsAttr.java > test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java > test/langtools/jdk/javadoc/tool/6964914/TestUserDoclet.java > test/langtools/jdk/javadoc/tool/EnsureNewOldDoclet.java > test/langtools/jdk/javadoc/tool/testLocaleOption/TestLocaleOption.java > test/langtools/tools/javac/T8132562/ClassPathWithDoubleQuotesTest.java > test/langtools/tools/javac/options/smokeTests/OptionSmokeTest.java > test/langtools/tools/javac/platform/PlatformProviderTest.java > test/langtools/tools/jdeps/MultiReleaseJar.java This pull request has now been integrated. Changeset: 7d545084 Author: Vikey Chen Committer: Ioi Lam URL: https://git.openjdk.java.net/jdk/commit/7d545084f45af44386cb38172fd783f889a8c4e7 Stats: 37 lines in 9 files changed: 14 ins; 0 del; 23 mod 8283606: Tests may fail with zh locale on MacOS Reviewed-by: iklam, rriggs ------------- PR: https://git.openjdk.java.net/jdk/pull/7924 From jjg at openjdk.java.net Thu May 5 00:34:03 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 00:34:03 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup Message-ID: Please review some cleanup updates to address issues reported by an IDE. The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. ------------- Commit messages: - JDK-8286153: Remove redundant casts and other cleanup Changes: https://git.openjdk.java.net/jdk/pull/8543/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8543&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8286153 Stats: 178 lines in 8 files changed: 4 ins; 48 del; 126 mod Patch: https://git.openjdk.java.net/jdk/pull/8543.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8543/head:pull/8543 PR: https://git.openjdk.java.net/jdk/pull/8543 From duke at openjdk.java.net Thu May 5 01:19:22 2022 From: duke at openjdk.java.net (Vikey Chen) Date: Thu, 5 May 2022 01:19:22 GMT Subject: RFR: 8283606: Tests may fail with zh locale on MacOS [v4] In-Reply-To: <21e-mJzcWAauSAEVbW0Icg2ELKkADKi1IgpcshgObfQ=.c65f5570-de08-444f-b6a4-e37509862267@github.com> References: <21e-mJzcWAauSAEVbW0Icg2ELKkADKi1IgpcshgObfQ=.c65f5570-de08-444f-b6a4-e37509862267@github.com> Message-ID: On Mon, 28 Mar 2022 17:00:39 GMT, Vikey Chen wrote: >> From the test doc of openjdk https://openjdk.java.net/groups/build/doc/testing.html >>> If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting LANG="en_US" in the environment before running tests should work. On Windows or MacOS, setting JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US" helps for most, but not all test cases. >> >> However, on MacOS 12.1, running `make test-tier1 JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"` command for tier-1 test, some tests still fail, including the following in tier-1.The tests expects output messages in English, but Chinese message are still produced. >> >> test/hotspot/jtreg/runtime/classFileParserBug/TestEmptyBootstrapMethodsAttr.java >> test/langtools/jdk/javadoc/tool/6964914/TestStdDoclet.java >> test/langtools/jdk/javadoc/tool/6964914/TestUserDoclet.java >> test/langtools/jdk/javadoc/tool/EnsureNewOldDoclet.java >> test/langtools/jdk/javadoc/tool/testLocaleOption/TestLocaleOption.java >> test/langtools/tools/javac/T8132562/ClassPathWithDoubleQuotesTest.java >> test/langtools/tools/javac/options/smokeTests/OptionSmokeTest.java >> test/langtools/tools/javac/platform/PlatformProviderTest.java >> test/langtools/tools/jdeps/MultiReleaseJar.java > > Vikey Chen has updated the pull request incrementally with one additional commit since the last revision: > > Locale.ENGLISH to Locale.US Thanks Ioi and Roger. ------------- PR: https://git.openjdk.java.net/jdk/pull/7924 From prappo at openjdk.java.net Thu May 5 10:35:31 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Thu, 5 May 2022 10:35:31 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: References: Message-ID: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> On Thu, 5 May 2022 00:18:56 GMT, Jonathan Gibbons wrote: > Please review some cleanup updates to address issues reported by an IDE. > > The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. > > Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 297: > 295: VisibleMemberTable vmt = configuration.getVisibleMemberTable(enclosing); > 296: // Check whether there is any implementation or overridden info to be > 297: // printed. If not overridden or implementation info needs to be Although awkward, it was correct before the change. Consider rewriting for clarity or deleting it. The code is pretty self-descriptive, if you ask me. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/MetaKeywords.java line 81: > 79: results.addAll(getMemberKeywords(utils.getMethods(typeElement))); > 80: } > 81: results.trimToSize(); I wonder if this method will look better this way: public List getMetaKeywords(TypeElement typeElement) { var results = new ArrayList(); ... results.trimToSize(); return results; } src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/MetaKeywords.java line 125: > 123: */ > 124: public List getOverviewMetaKeywords(String title, String docTitle) { > 125: List result = new ArrayList<>(1); Consider using `var` similarly to my suggestion above. Alternatively, we can use two calls to `List.of(e)` and one call to `List.of()`. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/MetaKeywords.java line 156: > 154: } > 155: } > 156: results.trimToSize(); Same suggestion for `var` as above. src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 273: > 271: * - is specified on the command line --module > 272: * - is derived from the module graph, that is, by expanding the > 273: * 'requires' directive, based on --expand-requires Thanks for using these clarifying quotes! src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1063: > 1061: if (enclosing != null) { > 1062: return switch (enclosing.getKind()) { > 1063: case CLASS, ENUM, RECORD, INTERFACE, ANNOTATION_TYPE -> visit(enclosing); Whoa! `RECORD` was missing. Does it make sense to accompany this PR with a small test that crashes javadoc with a type nested in a non-included record? src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1206: > 1204: AccessKind accessValue = null; > 1205: for (ElementKind kind : ALLOWED_KINDS) { > 1206: accessValue = switch (kind) { It feels awkward when adjacent `switch` statements use different formatting. ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From prappo at openjdk.java.net Thu May 5 10:42:18 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Thu, 5 May 2022 10:42:18 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> References: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> Message-ID: On Thu, 5 May 2022 10:30:17 GMT, Pavel Rappo wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. >> >> Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1206: > >> 1204: AccessKind accessValue = null; >> 1205: for (ElementKind kind : ALLOWED_KINDS) { >> 1206: accessValue = switch (kind) { > > It feels awkward when adjacent `switch` statements use different formatting. Correction: `switch` _expressions_ in this case. ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Thu May 5 14:43:15 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 14:43:15 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> References: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> Message-ID: On Thu, 5 May 2022 09:58:13 GMT, Pavel Rappo wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. >> >> Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 297: > >> 295: VisibleMemberTable vmt = configuration.getVisibleMemberTable(enclosing); >> 296: // Check whether there is any implementation or overridden info to be >> 297: // printed. If not overridden or implementation info needs to be > > Although awkward, it was correct before the change. Consider rewriting for clarity or deleting it. The code is pretty self-descriptive, if you ask me. ooops, will fix. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/MetaKeywords.java line 81: > >> 79: results.addAll(getMemberKeywords(utils.getMethods(typeElement))); >> 80: } >> 81: results.trimToSize(); > > I wonder if this method will look better this way: > > public List getMetaKeywords(TypeElement typeElement) { > var results = new ArrayList(); > ... > results.trimToSize(); > return results; > } Agreed; I was just trying to limit the cleanup. `var` is good. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/MetaKeywords.java line 156: > >> 154: } >> 155: } >> 156: results.trimToSize(); > > Same suggestion for `var` as above. ?? ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Thu May 5 14:48:26 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 14:48:26 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> References: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> Message-ID: <-pjWjo0LM2zj-LZVNEz77vhib8Atg6HPh_b9v99MqvY=.32d706f7-f981-4926-b5a8-e45e01e9877b@github.com> On Thu, 5 May 2022 10:17:16 GMT, Pavel Rappo wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. >> >> Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1063: > >> 1061: if (enclosing != null) { >> 1062: return switch (enclosing.getKind()) { >> 1063: case CLASS, ENUM, RECORD, INTERFACE, ANNOTATION_TYPE -> visit(enclosing); > > Whoa! `RECORD` was missing. Does it make sense to accompany this PR with a small test that crashes javadoc with a type nested in a non-included record? That's one possibility. Other possibilities: * a separate issue to audit use of ENUM to make sure there is matching RECORD entries, or * avoid using `default` to implicitly enable completeness checking, or * rewrite code to use `isDeclaredType`. ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Thu May 5 14:48:28 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 14:48:28 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: References: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> Message-ID: <94F_nOueNjtQ3coccUkZmbqDa2UaJAD9DTfcPf5Q5Ac=.f36712e0-36d2-4955-aa0a-e047159f7c83@github.com> On Thu, 5 May 2022 10:38:43 GMT, Pavel Rappo wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1206: >> >>> 1204: AccessKind accessValue = null; >>> 1205: for (ElementKind kind : ALLOWED_KINDS) { >>> 1206: accessValue = switch (kind) { >> >> It feels awkward when adjacent `switch` statements use different formatting. > > Correction: `switch` _expressions_ in this case. will examine; I was (generally) trying not to override IDE formatting. ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From hannesw at openjdk.java.net Thu May 5 14:50:25 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 5 May 2022 14:50:25 GMT Subject: RFR: JDK-8282559: Allow multiple search terms in javadoc search [v4] In-Reply-To: References: Message-ID: > Please review the first of two PRs to enhance JavaDoc search. > > This one focuses on the existing search script, to which it adds the feature to search for multiple terms. It also improves the implementation of case-sensitive search as well as rating of matches and provides some general update and refactoring of the script. > > The search section in the help page is updated to mention the multiple search term feature, and I repurposed the last example to show the new feature. > > The new search function can be tested here (top-level API doc files only): > http://cr.openjdk.java.net/~hannesw/8282559/api.00/ Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision: Add comma as suggested in review ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/8185/files - new: https://git.openjdk.java.net/jdk/pull/8185/files/8f178686..7d702a77 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=8185&range=03 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=8185&range=02-03 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/8185.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8185/head:pull/8185 PR: https://git.openjdk.java.net/jdk/pull/8185 From hannesw at openjdk.java.net Thu May 5 14:50:27 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 5 May 2022 14:50:27 GMT Subject: RFR: JDK-8282559: Allow multiple search terms in javadoc search [v3] In-Reply-To: References: <2AWn6UB3IjF2gWcZ_Fuu9bn1V8zgVu0JyxecCmwUUPA=.39acddc4-0274-4c3c-bedf-d1d3691c1312@github.com> Message-ID: <4Bk0dgYfR-foWW84Xi0QUPsp0W9Hw1K1SaEAGvU2CwI=.48bef29e-16ca-406a-bfe2-01bfef87d5a0@github.com> On Wed, 4 May 2022 20:33:28 GMT, Jonathan Gibbons wrote: > Approved, with a grammar suggestion. Thanks for the thumbs up, I added a commit with the suggested comma. ------------- PR: https://git.openjdk.java.net/jdk/pull/8185 From hannesw at openjdk.java.net Thu May 5 14:50:30 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 5 May 2022 14:50:30 GMT Subject: Integrated: JDK-8282559: Allow multiple search terms in javadoc search In-Reply-To: References: Message-ID: <4Jsh139HfcOLG8m-m51aEm1sC8xC6h4Cpl4rK7Tf4KQ=.fd753a60-4e70-4180-9cae-5281b902c2db@github.com> On Mon, 11 Apr 2022 17:06:05 GMT, Hannes Walln?fer wrote: > Please review the first of two PRs to enhance JavaDoc search. > > This one focuses on the existing search script, to which it adds the feature to search for multiple terms. It also improves the implementation of case-sensitive search as well as rating of matches and provides some general update and refactoring of the script. > > The search section in the help page is updated to mention the multiple search term feature, and I repurposed the last example to show the new feature. > > The new search function can be tested here (top-level API doc files only): > http://cr.openjdk.java.net/~hannesw/8282559/api.00/ This pull request has now been integrated. Changeset: 5ac7186c Author: Hannes Walln?fer URL: https://git.openjdk.java.net/jdk/commit/5ac7186c9e2ea1e3bdbd8e10429feb520d1aedf8 Stats: 542 lines in 7 files changed: 221 ins; 167 del; 154 mod 8282559: Allow multiple search terms in javadoc search Reviewed-by: jjg ------------- PR: https://git.openjdk.java.net/jdk/pull/8185 From duke at openjdk.java.net Thu May 5 14:53:17 2022 From: duke at openjdk.java.net (openjdk-notifier[bot]) Date: Thu, 5 May 2022 14:53:17 GMT Subject: RFR: JDK-8248863: Add search landing page to API documentation [v3] In-Reply-To: References: Message-ID: On Tue, 19 Apr 2022 21:04:04 GMT, Hannes Walln?fer wrote: >> This is the second of two PRs to enhance JavaDoc search, it is based on the first one (#8185). >> >> It adds a standalone search page (search.html) along with its own script file (search-page.js). This PR is very similar to the last prototype I uploaded and demoed, the changes are mostly tweaks to the markup, style sheets and text. >> >> JDK API docs rendered with this patch can be viewed and tested here (top-level files only, updated on April 20th): >> http://cr.openjdk.java.net/~hannesw/8248863/api.02/ >> http://cr.openjdk.java.net/~hannesw/8248863/api.02/search.html > > Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision: > > - Use different max results values for popup and page search > - Fix search link height The dependent pull request has now been integrated, and the target branch of this pull request has been updated. This means that changes from the dependent pull request can start to show up as belonging to this pull request, which may be confusing for reviewers. To remedy this situation, simply merge the latest changes from the new target branch into this pull request by running commands similar to these in the local repository for your personal fork: git checkout JDK-8248863 git fetch https://git.openjdk.java.net/jdk master git merge FETCH_HEAD # if there are conflicts, follow the instructions given by git merge git commit -m "Merge master" git push ------------- PR: https://git.openjdk.java.net/jdk/pull/8226 From jjg at openjdk.java.net Thu May 5 16:33:17 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 16:33:17 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> References: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> Message-ID: On Thu, 5 May 2022 10:09:32 GMT, Pavel Rappo wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. >> >> Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/MetaKeywords.java line 125: > >> 123: */ >> 124: public List getOverviewMetaKeywords(String title, String docTitle) { >> 125: List result = new ArrayList<>(1); > > Consider using `var` similarly to my suggestion above. Alternatively, we can use two calls to `List.of(e)` and one call to `List.of()`. Most of these cases seem better with appropriate variants of `List.of` ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From hannesw at openjdk.java.net Thu May 5 16:56:20 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Thu, 5 May 2022 16:56:20 GMT Subject: RFR: JDK-8248863: Add search landing page to API documentation [v4] In-Reply-To: References: Message-ID: > This is the second of two PRs to enhance JavaDoc search, it is based on the first one (#8185). > > It adds a standalone search page (search.html) along with its own script file (search-page.js). This PR is very similar to the last prototype I uploaded and demoed, the changes are mostly tweaks to the markup, style sheets and text. > > JDK API docs rendered with this patch can be viewed and tested here (top-level files only, updated on April 20th): > http://cr.openjdk.java.net/~hannesw/8248863/api.02/ > http://cr.openjdk.java.net/~hannesw/8248863/api.02/search.html Hannes Walln?fer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits: - Merge master - Use different max results values for popup and page search - Fix search link height - First round of feedback - JDK-8248863: Add search landing page to API documentation - Update copyright headers - JDK-8282559: Allow multiple search terms in javadoc search ------------- Changes: https://git.openjdk.java.net/jdk/pull/8226/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8226&range=03 Stats: 742 lines in 20 files changed: 678 ins; 7 del; 57 mod Patch: https://git.openjdk.java.net/jdk/pull/8226.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8226/head:pull/8226 PR: https://git.openjdk.java.net/jdk/pull/8226 From jjg at openjdk.java.net Thu May 5 16:58:37 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 16:58:37 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: <-pjWjo0LM2zj-LZVNEz77vhib8Atg6HPh_b9v99MqvY=.32d706f7-f981-4926-b5a8-e45e01e9877b@github.com> References: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> <-pjWjo0LM2zj-LZVNEz77vhib8Atg6HPh_b9v99MqvY=.32d706f7-f981-4926-b5a8-e45e01e9877b@github.com> Message-ID: On Thu, 5 May 2022 14:43:37 GMT, Jonathan Gibbons wrote: >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/ElementsTable.java line 1063: >> >>> 1061: if (enclosing != null) { >>> 1062: return switch (enclosing.getKind()) { >>> 1063: case CLASS, ENUM, RECORD, INTERFACE, ANNOTATION_TYPE -> visit(enclosing); >> >> Whoa! `RECORD` was missing. Does it make sense to accompany this PR with a small test that crashes javadoc with a type nested in a non-included record? > > That's one possibility. > > Other possibilities: > * a separate issue to audit use of ENUM to make sure there is matching RECORD entries, or > * avoid using `default` to implicitly enable completeness checking, or > * rewrite code to use `isDeclaredType`. I've reviewed all uses of `ENUM`. All other places in javadoc look OK for having a sibling case for `RECORD`. Filed [JDK-8286205](https://bugs.openjdk.java.net/browse/JDK-8286205) for more tests. ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Thu May 5 16:58:38 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 16:58:38 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: <94F_nOueNjtQ3coccUkZmbqDa2UaJAD9DTfcPf5Q5Ac=.f36712e0-36d2-4955-aa0a-e047159f7c83@github.com> References: <62WVOvplu9-HsethplNoiik24Hd_x0xeD8IwoSk5Jeo=.368fd047-1051-4265-bfda-cd05f18b54c1@github.com> <94F_nOueNjtQ3coccUkZmbqDa2UaJAD9DTfcPf5Q5Ac=.f36712e0-36d2-4955-aa0a-e047159f7c83@github.com> Message-ID: On Thu, 5 May 2022 14:43:52 GMT, Jonathan Gibbons wrote: >> Correction: `switch` _expressions_ in this case. > > will examine; I was (generally) trying not to override IDE formatting. fixed ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Thu May 5 17:20:25 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 5 May 2022 17:20:25 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup [v2] In-Reply-To: References: Message-ID: > Please review some cleanup updates to address issues reported by an IDE. > > The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. > > Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/8543/files - new: https://git.openjdk.java.net/jdk/pull/8543/files/e18b0b6c..6ad78546 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=8543&range=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=8543&range=00-01 Stats: 25 lines in 3 files changed: 3 ins; 7 del; 15 mod Patch: https://git.openjdk.java.net/jdk/pull/8543.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8543/head:pull/8543 PR: https://git.openjdk.java.net/jdk/pull/8543 From prappo at openjdk.java.net Thu May 5 18:14:15 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Thu, 5 May 2022 18:14:15 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup [v2] In-Reply-To: References: Message-ID: <1jUabMO7GyTq2wSH7sjeDMm6J23T6RSwB_y0zL7Js6Q=.d356bc68-d823-4e27-913b-182924eba2d0@github.com> On Thu, 5 May 2022 17:20:25 GMT, Jonathan Gibbons wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. >> >> Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. > > Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: > > address review feedback Marked as reviewed by prappo (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From duke at openjdk.java.net Thu May 5 23:58:50 2022 From: duke at openjdk.java.net (liach) Date: Thu, 5 May 2022 23:58:50 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup [v2] In-Reply-To: References: Message-ID: On Thu, 5 May 2022 17:20:25 GMT, Jonathan Gibbons wrote: >> Please review some cleanup updates to address issues reported by an IDE. >> >> The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. >> >> Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. > > Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: > > address review feedback src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java line 224: > 222: mapTypeParameters(classToFieldTypeParam, fd, fd); > 223: mapAnnotations(annotationToField, fd, fd); > 224: var stv = new SimpleTypeVisitor9() { Extra space before `var` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 1528: > 1526: instance.setStrength(strength); > 1527: > 1528: keys = new LinkedHashMap<>(MAX_SIZE + 1, 0.75f, true) { This map's initial capacity requires it to resize before it starts evicting, see https://github.com/openjdk/jdk/blob/7ebc4bce930e7d406f1e68c8bd09ac1dc3a21e5a/src/java.base/share/classes/java/util/HashMap.java#L2563 ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Fri May 6 00:04:55 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 6 May 2022 00:04:55 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup [v2] In-Reply-To: References: Message-ID: <657Y9BJK5w9dmOZtXbb-sTMoOP5ciA2CyTaPv1aj92U=.43aa7edd-c45d-4e78-afd4-1d486d056d83@github.com> On Thu, 5 May 2022 23:51:59 GMT, liach wrote: >> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: >> >> address review feedback > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java line 224: > >> 222: mapTypeParameters(classToFieldTypeParam, fd, fd); >> 223: mapAnnotations(annotationToField, fd, fd); >> 224: var stv = new SimpleTypeVisitor9() { > > Extra space before `var` Thanks, will fix. > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java line 1528: > >> 1526: instance.setStrength(strength); >> 1527: >> 1528: keys = new LinkedHashMap<>(MAX_SIZE + 1, 0.75f, true) { > > This map's initial capacity requires it to resize before it starts evicting, see https://github.com/openjdk/jdk/blob/7ebc4bce930e7d406f1e68c8bd09ac1dc3a21e5a/src/java.base/share/classes/java/util/HashMap.java#L2563 > > Can either increase the initial capacity or change the load factor to 1.0f. Not in this PR. ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Fri May 6 00:20:45 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 6 May 2022 00:20:45 GMT Subject: RFR: JDK-8286153: Remove redundant casts and other cleanup [v3] In-Reply-To: References: Message-ID: > Please review some cleanup updates to address issues reported by an IDE. > > The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. > > Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: fix indentation ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/8543/files - new: https://git.openjdk.java.net/jdk/pull/8543/files/6ad78546..34fd6970 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=8543&range=02 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=8543&range=01-02 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/8543.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8543/head:pull/8543 PR: https://git.openjdk.java.net/jdk/pull/8543 From jjg at openjdk.java.net Fri May 6 00:20:45 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 6 May 2022 00:20:45 GMT Subject: Integrated: JDK-8286153: Remove redundant casts and other cleanup In-Reply-To: References: Message-ID: On Thu, 5 May 2022 00:18:56 GMT, Jonathan Gibbons wrote: > Please review some cleanup updates to address issues reported by an IDE. > > The seeds for the change were a series of redundant casts, that have now all been removed. Various other warnings and suggestions were made by the IDE for the affected files. There were a number of places with redundant type arguments, for which the general fix was in favor of using `var` instead of `<>`. > > Some `switch` statements were converted to the enhanced `switch` form, which also revealed a couple of places where `RECORD` should have been added alongside `ENUM`. This pull request has now been integrated. Changeset: 9425ab2b Author: Jonathan Gibbons URL: https://git.openjdk.java.net/jdk/commit/9425ab2b43b649bd591706bfc820e9c8795a6fdf Stats: 197 lines in 8 files changed: 7 ins; 55 del; 135 mod 8286153: Remove redundant casts and other cleanup Reviewed-by: prappo ------------- PR: https://git.openjdk.java.net/jdk/pull/8543 From hannesw at openjdk.java.net Fri May 6 09:01:52 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 6 May 2022 09:01:52 GMT Subject: Integrated: JDK-8248863: Add search landing page to API documentation In-Reply-To: References: Message-ID: On Wed, 13 Apr 2022 16:01:17 GMT, Hannes Walln?fer wrote: > This is the second of two PRs to enhance JavaDoc search, it is based on the first one (#8185). > > It adds a standalone search page (search.html) along with its own script file (search-page.js). This PR is very similar to the last prototype I uploaded and demoed, the changes are mostly tweaks to the markup, style sheets and text. > > JDK API docs rendered with this patch can be viewed and tested here (top-level files only, updated on April 20th): > http://cr.openjdk.java.net/~hannesw/8248863/api.02/ > http://cr.openjdk.java.net/~hannesw/8248863/api.02/search.html This pull request has now been integrated. Changeset: 3cdedf1d Author: Hannes Walln?fer URL: https://git.openjdk.java.net/jdk/commit/3cdedf1ddb1b5058fd3d02891b4099964e4b4df2 Stats: 742 lines in 20 files changed: 678 ins; 7 del; 57 mod 8248863: Add search landing page to API documentation Reviewed-by: jjg ------------- PR: https://git.openjdk.java.net/jdk/pull/8226 From jjg at openjdk.java.net Fri May 6 22:13:22 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 6 May 2022 22:13:22 GMT Subject: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated. Message-ID: Please review a simple small change to `TagletManager`, to not report warnings about bad use of tags (such as `@author` and `@version`) when command-line options have not been given to enable the use of the tags in the output (i.e. the `-author` and the dreadfully-named `-version` option.) The change is more pragmatic than anything else. There are lots of "bad" uses of `@author` in JDK API documentation, on methods. The alternative would be to permit the tag anywhere, but that would be both a spec change and work to implement the change that we're not really interest in, since the tag is now somewhat deprecated. Two existing tests are updated, to test the handling of "bad" tags, with and without the enabling option. Another test has some very (very) old unused lines deleted. If today was Thursday, I'd call it Throwback Thursday. These lines predate the `JavadocTester` conversion. ------------- Commit messages: - JDK-8286338: suppress warnings about bad @author tags when author info is not generated. Changes: https://git.openjdk.java.net/jdk/pull/8583/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8583&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8286338 Stats: 99 lines in 4 files changed: 86 ins; 10 del; 3 mod Patch: https://git.openjdk.java.net/jdk/pull/8583.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8583/head:pull/8583 PR: https://git.openjdk.java.net/jdk/pull/8583 From prappo at openjdk.java.net Fri May 6 22:28:56 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Fri, 6 May 2022 22:28:56 GMT Subject: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated. In-Reply-To: References: Message-ID: On Fri, 6 May 2022 22:06:17 GMT, Jonathan Gibbons wrote: > Please review a simple small change to `TagletManager`, to not report warnings about bad use of tags (such as `@author` and `@version`) when command-line options have not been given to enable the use of the tags in the output (i.e. the `-author` and the dreadfully-named `-version` option.) > > The change is more pragmatic than anything else. There are lots of "bad" uses of `@author` in JDK API documentation, on methods. The alternative would be to permit the tag anywhere, but that would be both a spec change and work to implement the change that we're not really interest in, since the tag is now somewhat deprecated. > > Two existing tests are updated, to test the handling of "bad" tags, with and without the enabling option. > > Another test has some very (very) old unused lines deleted. If today was Thursday, I'd call it Throwback Thursday. These lines predate the `JavadocTester` conversion. What's that `-XDdummy=dummy` you use in tests? test/langtools/jdk/javadoc/doclet/testSimpleTagInherit/TestSimpleTagInherit.java line 38: > 36: public class TestSimpleTagInherit extends JavadocTester { > 37: > 38: //Javadoc arguments. This seems like an unrelated change; is it cleanup? test/langtools/jdk/javadoc/doclet/testVersionTag/TestVersionTag.java line 57: > 55: """ > 56: package pkg; > 57: /** Introduction. Cleanup? ------------- PR: https://git.openjdk.java.net/jdk/pull/8583 From hannesw at openjdk.java.net Wed May 11 16:49:21 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Wed, 11 May 2022 16:49:21 GMT Subject: RFR: JDK-8268422: Find a better way to select releases in "New API" page Message-ID: This is a conceptually simple change, but it has a few ramifications that make it at least look a bit bigger than it is. At the core, this adds a new method to the `Table` class that allows to generate tables with multiple categories but omit the generation of table tabs. This is used in the "New API" and "Deprecated API" pages to render the release selectors as a global row of checkboxes that control release information for all tables in the page. Also, the element name and release columns in those pages are now sortable by clicking on the table headers. Output generated with this change is available here: http://cr.openjdk.java.net/~hannesw/8268422/api.06/new-list.html http://cr.openjdk.java.net/~hannesw/8268422/api.06/deprecated-list.html Now to the details and aforementioned ramifications: - Since I added new functionality to the table class I thought it woudl be a good occasion to remove some other functionality that was never really used by our code. This includes the possibility to set the table tab and striped row styles. We always use the default styles for these, and if somebody wanted to change the look of the styles the way to go would be to change the style definitions in the stylesheets rather then the style names. This change made the inclusion of a table-specific script obsolete, so you'll see some removals of `table.needsScript()` and `table.getScript()` in unrelated code. - `SummaryListWriter`, the base class for the New API and Deprecated API pages, gets a few new protected methods that are overridden in subclasses to generate the extra content as needed. I think the solution is suboptimal and a bit noisy. The protected classes have generic names such as `getExtraContent` and the parent class is not really aware of the different releases, since one subclass never displays multi-release information (Preview API), one does sometimes (Deprecated API) and one does always (New API). I think we could come up with a nicer solution, but I think it's not terrible and didn't want to delay integration too much. - We have yet more JavaScript for global table category selection and sortable table columns as well as new CSS classes, including inlined SVGs for the sortable column icons. I tried to keep the additions as small and clean as possible and added a short comment for each function. - The changes in `TestNewApiList.java` are huge. I couldn't have made those changes without improving the output of `JavadocTester` by adding the output directory to the test name. This change makes it much easier to read jtreg output for tests with many similar but slightly different checks. I probably should have done this a long time ago! ------------- Commit messages: - Add @bug id, fix indentation - Comment wording - JDK-8268422: Find a better way to select releases in "New API" page Changes: https://git.openjdk.java.net/jdk/pull/8657/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8657&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8268422 Stats: 1089 lines in 22 files changed: 442 ins; 283 del; 364 mod Patch: https://git.openjdk.java.net/jdk/pull/8657.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8657/head:pull/8657 PR: https://git.openjdk.java.net/jdk/pull/8657 From jjg at openjdk.java.net Thu May 12 23:15:47 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 12 May 2022 23:15:47 GMT Subject: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated. In-Reply-To: References: Message-ID: On Fri, 6 May 2022 22:25:30 GMT, Pavel Rappo wrote: > What's that `-XDdummy=dummy` you use in tests? It's a no-op placeholder. JavaDoc does not allow empty arguments, and the alternative is dynamically build a list with a conditional component. `-XD` is a "hidden" option to inject values in the compiler options map, so `-XDdummy=dummy` just injects a dummy value there. > test/langtools/jdk/javadoc/doclet/testSimpleTagInherit/TestSimpleTagInherit.java line 38: > >> 36: public class TestSimpleTagInherit extends JavadocTester { >> 37: >> 38: //Javadoc arguments. > > This seems like an unrelated change; is it cleanup? Yes, this is a holdover from the bad old days before `JavadocTester`, when tests were set up using fixed arrays like these. Frankly, I'm surprised these two empty arrays escaped notice for so long. > test/langtools/jdk/javadoc/doclet/testVersionTag/TestVersionTag.java line 57: > >> 55: """ >> 56: package pkg; >> 57: /** Introduction. > > Cleanup? yes ------------- PR: https://git.openjdk.java.net/jdk/pull/8583 From prappo at openjdk.java.net Fri May 13 09:10:49 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Fri, 13 May 2022 09:10:49 GMT Subject: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated. In-Reply-To: References: Message-ID: On Fri, 6 May 2022 22:06:17 GMT, Jonathan Gibbons wrote: > Please review a simple small change to `TagletManager`, to not report warnings about bad use of tags (such as `@author` and `@version`) when command-line options have not been given to enable the use of the tags in the output (i.e. the `-author` and the dreadfully-named `-version` option.) > > The change is more pragmatic than anything else. There are lots of "bad" uses of `@author` in JDK API documentation, on methods. The alternative would be to permit the tag anywhere, but that would be both a spec change and work to implement the change that we're not really interest in, since the tag is now somewhat deprecated. > > Two existing tests are updated, to test the handling of "bad" tags, with and without the enabling option. > > Another test has some very (very) old unused lines deleted. If today was Thursday, I'd call it Throwback Thursday. These lines predate the `JavadocTester` conversion. Marked as reviewed by prappo (Reviewer). ------------- PR: https://git.openjdk.java.net/jdk/pull/8583 From prappo at openjdk.java.net Fri May 13 09:10:49 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Fri, 13 May 2022 09:10:49 GMT Subject: RFR: JDK-8286338: suppress warnings about bad @author tags when author info is not generated. In-Reply-To: References: Message-ID: On Thu, 12 May 2022 23:10:36 GMT, Jonathan Gibbons wrote: > > What's that `-XDdummy=dummy` you use in tests? > > It's a no-op placeholder. JavaDoc does not allow empty arguments, and the alternative is dynamically build a list with a conditional component. `-XD` is a "hidden" option to inject values in the compiler options map, so `-XDdummy=dummy` just injects a dummy value there. Okay, I can see what happens when you pass an empty string: error: Illegal package name: "" I wish there were a better way of conditionally providing a javadoc option. ------------- PR: https://git.openjdk.java.net/jdk/pull/8583 From hannesw at openjdk.java.net Fri May 13 13:56:22 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 13 May 2022 13:56:22 GMT Subject: RFR: JDK-8284367: JQuery UI upgrade from 1.12.1 to 1.13.1 Message-ID: This updates jQuery UI (which is used for the javadoc in-age search feature) to version 1.13.1. Rendered documentation is available here: http://cr.openjdk.java.net/~hannesw/8284367/api.00/ I noticed that we are carrying a lot of files from the jQuery UI distribution that we don't really need. this includes the jquery-ui.structure.css files (both minified and non-minified) as well as the icon image files. These files are not used or referenced anywhere in our generated documentation so I removed them instead of updating them. I also decided to update to the unthemed jQuery UI version as wee don't really use the theme. Some minor changes in our stylesheets were required to avoid unwanted layout changes: - Add a definition for 1px border around the selelcted list item in our jquery-ui.overrides CSS file. Without this, the the new jQuery UI would display a blue border or no border at all depending on the theme. The border is now orange so it is not distinguishable from the selected background, but it is necessary to keep the item in the same position when it is selected. - Remove the `font-size: 13px` property from the `.result-item` class. This was necessary because previously this class used `font-family: Verdana` from the jQuery UI theme which looks bigger and is also inconsistent with the fonts we use in the rest of the page. Now that the search result list uses the same fonts as the rest of the page we can go back to using the inherited font size. I left the `font-size` property and changed the value to `inherit` because our tests don't like CSS classes that are not present in the stylesheet. - Finally I had to add a property to the `ul.ui-autocomplete` list to explicitly set the background to white. The update made the background transparent. I'm not sure if this is a result of the missing theme but it was simple enough to fix. ------------- Commit messages: - Minimize style tweaks - Remove unused jquery-ui files - Small style fixes - Update to jquery-ui 1.13.1 with no theme Changes: https://git.openjdk.java.net/jdk/pull/8702/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8702&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8284367 Stats: 889 lines in 12 files changed: 125 ins; 697 del; 67 mod Patch: https://git.openjdk.java.net/jdk/pull/8702.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8702/head:pull/8702 PR: https://git.openjdk.java.net/jdk/pull/8702 From jjg at openjdk.java.net Fri May 13 22:24:16 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Fri, 13 May 2022 22:24:16 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package Message-ID: Please review a small fix to address use of snippets in source code in the unnamed package. The core of the fix is to replace `packageName(pkg, utils)` (which returns `""` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.) There's some minor localized cleanup and rearrangement as well. The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package. ------------- Commit messages: - fix whitespace - JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package Changes: https://git.openjdk.java.net/jdk/pull/8708/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8708&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8284037 Stats: 110 lines in 2 files changed: 102 ins; 7 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/8708.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8708/head:pull/8708 PR: https://git.openjdk.java.net/jdk/pull/8708 From hannesw at openjdk.java.net Mon May 16 09:32:48 2022 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Mon, 16 May 2022 09:32:48 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package In-Reply-To: References: Message-ID: <1NsSaEL4rBi9neFE7GHaj-viOvhcYjgVgL5T6rQXeos=.966d2303-e64b-48d8-903a-5114c520e45d@github.com> On Fri, 13 May 2022 21:51:32 GMT, Jonathan Gibbons wrote: > Please review a small fix to address use of snippets in source code in the unnamed package. > > The core of the fix is to replace `packageName(pkg, utils)` (which returns `""` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.) > > There's some minor localized cleanup and rearrangement as well. > > The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package. test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetUnnamedPackage.java line 84: > 82: checkExit(useSourcePath ? Exit.OK : Exit.ERROR); > 83: checkOutput(Output.OUT, !useSourcePath, > 84: "C.java:4: error: file not found on source path or snippet path: S.java"); I must admit I don't understand the rules for snippet discovery with or without --source-path argument. Would the same behavior be expcected for code in a named package? ------------- PR: https://git.openjdk.java.net/jdk/pull/8708 From prappo at openjdk.java.net Mon May 16 10:38:49 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Mon, 16 May 2022 10:38:49 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package In-Reply-To: References: Message-ID: <29VC4YZIhUhIr2vYtiHRObx8LEHod2iLqwTdX7XOsRw=.05917213-4194-40d1-95f7-0f3cd65e6b5f@github.com> On Fri, 13 May 2022 21:51:32 GMT, Jonathan Gibbons wrote: > Please review a small fix to address use of snippets in source code in the unnamed package. > > The core of the fix is to replace `packageName(pkg, utils)` (which returns `""` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.) > > There's some minor localized cleanup and rearrangement as well. > > The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 221: > 219: var utils = writer.configuration().utils; > 220: var pkg = getPackageElement(holder, utils); > 221: var pkgLocn = utils.getLocationForPackage(pkg); Can the name be `pkgLocation`? test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetUnnamedPackage.java line 82: > 80: > 81: javadoc(args.toArray(String[]::new)); > 82: checkExit(useSourcePath ? Exit.OK : Exit.ERROR); Thanks for taking into account our discussion in #8583. On the one hand, this way of conditionally adding an option is more mouthful. On the other hand, it doesn't make a first-time reader scratch their head and makes for a cleaner test. ------------- PR: https://git.openjdk.java.net/jdk/pull/8708 From prappo at openjdk.java.net Mon May 16 10:43:43 2022 From: prappo at openjdk.java.net (Pavel Rappo) Date: Mon, 16 May 2022 10:43:43 GMT Subject: RFR: JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section In-Reply-To: References: Message-ID: On Tue, 3 May 2022 20:38:44 GMT, Jonathan Gibbons wrote: > As described in the JBS issue, the observed problem is a side-effect of a related but different issue, which is that record classes are not treated the same was as enum classes when it comes to generating the class hierarchy in `ClassTree`. Because record classes are not treated specially/differently, they are treated as ordinary/plain classes, with the side-effect that the page for `java.lang.Record` shows `Direct Known Subclasses`. > > The underlying fix is therefore to clone the enum support in `ClassTree` and related classes, to provide support for record classes. It is possible to do an extreme minimal clone, but that just clones some of the messy evolution already there. Instead, the code in `ClassTree` and its clients is refactored and modernized. > > Previously there were four explicit pairs of member fields, containing data for different groups (hierarchies) of classes, namely: plain classes, enum classes, interfaces and annotation interfaces. These fields are most of the code to support them are moved into some new abstractions to encapsulate related functionality. > > 1. The main new abstraction in `ClassTree` is `Hierarchy` which provides the support for the different hierarchies displayed in the generated pages. > 2. A new enum `HierarchyKind` identifies the four existing hierarchies (listed above) and now a new one, for record classes. The hierarchies correspond to the different kinds of declared type. > 3. A small new class `SubtypeMap` which is a multi-map for mapping a type element to its subtypes. This is used in `Hierarchy` and to record the classes that implement an interfaces. > > Generally, the naming should be clearer and more obvious. The most confusing name in the old code was `enumSubtypes` which was weird because enum classes don't have subtypes. It meant "subtypes of supertypes of enum classes". This was a prime motivator to switch to the `hierarchy` terminology. The variant spellings of `intfacs` have all been replaced by `interfaces`, and `classtree` becomes `classTree`. > > *Testing*: a new test case has been added to the `TestRecordTypes.java` test, which verifies the new record hierarchy is displayed on a a package tree page. It is not simple to directly test the observed/reported behavior, because it is specific to the JDK API documentation, and because it is about the content of the `java.lang.Record` API page. However, manual inspection and diff comparison between JDK API documentation generated before and after this change reveals only expected differences. These differences are on the `java.lang.R4cord` page (where the offending section is no longer displayed) and on the pages related to the two existing records in JDK ... which are now listed in `Record Class Hierarchy` sections in the appropriate `package-tree.html` files. Please merge this branch with the master (they are now in conflict) and I will review the change. ------------- PR: https://git.openjdk.java.net/jdk/pull/8523 From jjg at openjdk.java.net Mon May 16 22:46:38 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Mon, 16 May 2022 22:46:38 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package In-Reply-To: <1NsSaEL4rBi9neFE7GHaj-viOvhcYjgVgL5T6rQXeos=.966d2303-e64b-48d8-903a-5114c520e45d@github.com> References: <1NsSaEL4rBi9neFE7GHaj-viOvhcYjgVgL5T6rQXeos=.966d2303-e64b-48d8-903a-5114c520e45d@github.com> Message-ID: On Mon, 16 May 2022 09:29:19 GMT, Hannes Walln?fer wrote: >> Please review a small fix to address use of snippets in source code in the unnamed package. >> >> The core of the fix is to replace `packageName(pkg, utils)` (which returns `""` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.) >> >> There's some minor localized cleanup and rearrangement as well. >> >> The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package. > > test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetUnnamedPackage.java line 84: > >> 82: checkExit(useSourcePath ? Exit.OK : Exit.ERROR); >> 83: checkOutput(Output.OUT, !useSourcePath, >> 84: "C.java:4: error: file not found on source path or snippet path: S.java"); > > I must admit I don't understand the rules for snippet discovery with or without --source-path argument. Would the same behavior be expcected for code in a named package? Well, the correct behavior is the same for both named and unnamed packages, but the bug was specifically about the use of the unnamed package. The correct behavior is that snippet files are first looked up on the source path (`--source-path` and friends), in the appropriate `snippet-files` subdirectory relative to the enclosing package, and if not found there, the snippet files are looked for on the snippet path (`--snippet-path`). (( _An interesting corollary is that the `snippet-files` subdirectory does not need to be a direct subdirectory of the directory containing the snippet tag: it just has to exist with that name somewhere on the path. This could maybe be used by users and IDEs to their advantage._ )) The underlying javac "rule" is that files are either given on the command-line or looked up on some search path. Snippet files can't be specified on the command-line; therefore, they must be found on a search path: in this case, either the source path or the snippet path. The bug fixed in this issue was related to creating the name to give to the file manager. For the file manager, the unnamed package is represented by an empty string. We were (incorrectly) using the strings ``. oops. ------------- PR: https://git.openjdk.java.net/jdk/pull/8708 From jjg at openjdk.java.net Mon May 16 22:54:33 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Mon, 16 May 2022 22:54:33 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package In-Reply-To: <29VC4YZIhUhIr2vYtiHRObx8LEHod2iLqwTdX7XOsRw=.05917213-4194-40d1-95f7-0f3cd65e6b5f@github.com> References: <29VC4YZIhUhIr2vYtiHRObx8LEHod2iLqwTdX7XOsRw=.05917213-4194-40d1-95f7-0f3cd65e6b5f@github.com> Message-ID: On Mon, 16 May 2022 10:31:25 GMT, Pavel Rappo wrote: >> Please review a small fix to address use of snippets in source code in the unnamed package. >> >> The core of the fix is to replace `packageName(pkg, utils)` (which returns `""` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.) >> >> There's some minor localized cleanup and rearrangement as well. >> >> The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package. > > test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetUnnamedPackage.java line 82: > >> 80: >> 81: javadoc(args.toArray(String[]::new)); >> 82: checkExit(useSourcePath ? Exit.OK : Exit.ERROR); > > Thanks for taking into account our discussion in #8583. > > On the one hand, this way of conditionally adding an option is more mouthful. On the other hand, it doesn't make a first-time reader scratch their head and makes for a cleaner test. Going forward, how about an `Args` builder, with fluent methods `add(String)`, `addAll(String...)`, `addAll(List)` and `add(Optional)` ... although that last one will cause warnings from javac which grumbles about using `Optional` as a parameter type. Instead of using `Optional`, we could have overloads `addIf(boolean, String)` etc. I'm open to suggestions for a better/neater methodology here. ------------- PR: https://git.openjdk.java.net/jdk/pull/8708 From jjg at openjdk.java.net Mon May 16 23:00:38 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Mon, 16 May 2022 23:00:38 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package In-Reply-To: <29VC4YZIhUhIr2vYtiHRObx8LEHod2iLqwTdX7XOsRw=.05917213-4194-40d1-95f7-0f3cd65e6b5f@github.com> References: <29VC4YZIhUhIr2vYtiHRObx8LEHod2iLqwTdX7XOsRw=.05917213-4194-40d1-95f7-0f3cd65e6b5f@github.com> Message-ID: <0xNa-lewRHIuvW7Y0VoxvTyShKHd9W2aGUM5sE3-XMQ=.be592738-f114-4a80-ac8b-6f8105feb2b2@github.com> On Mon, 16 May 2022 10:14:06 GMT, Pavel Rappo wrote: >> Please review a small fix to address use of snippets in source code in the unnamed package. >> >> The core of the fix is to replace `packageName(pkg, utils)` (which returns `""` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.) >> >> There's some minor localized cleanup and rearrangement as well. >> >> The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package. > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SnippetTaglet.java line 221: > >> 219: var utils = writer.configuration().utils; >> 220: var pkg = getPackageElement(holder, utils); >> 221: var pkgLocn = utils.getLocationForPackage(pkg); > > Can the name be `pkgLocation`? Yeah, I guess so ;-) ------------- PR: https://git.openjdk.java.net/jdk/pull/8708 From jjg at openjdk.java.net Mon May 16 23:00:39 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Mon, 16 May 2022 23:00:39 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package In-Reply-To: References: <29VC4YZIhUhIr2vYtiHRObx8LEHod2iLqwTdX7XOsRw=.05917213-4194-40d1-95f7-0f3cd65e6b5f@github.com> Message-ID: On Mon, 16 May 2022 22:49:09 GMT, Jonathan Gibbons wrote: >> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetUnnamedPackage.java line 82: >> >>> 80: >>> 81: javadoc(args.toArray(String[]::new)); >>> 82: checkExit(useSourcePath ? Exit.OK : Exit.ERROR); >> >> Thanks for taking into account our discussion in #8583. >> >> On the one hand, this way of conditionally adding an option is more mouthful. On the other hand, it doesn't make a first-time reader scratch their head and makes for a cleaner test. > > Going forward, how about an `Args` builder, with fluent methods `add(String)`, `addAll(String...)`, `addAll(List)` and `add(Optional)` ... although that last one will cause warnings from javac which grumbles about using `Optional` as a parameter type. > > Instead of using `Optional`, we could have overloads `addIf(boolean, String)` etc. > > I'm open to suggestions for a better/neater methodology here. [JDK-8286842](https://bugs.openjdk.java.net/browse/JDK-8286842) ------------- PR: https://git.openjdk.java.net/jdk/pull/8708 From jjg at openjdk.java.net Mon May 16 23:16:25 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Mon, 16 May 2022 23:16:25 GMT Subject: RFR: JDK-8284037: Snippet-files subdirectory not automatically detected when in unnamed package [v2] In-Reply-To: References: Message-ID: > Please review a small fix to address use of snippets in source code in the unnamed package. > > The core of the fix is to replace `packageName(pkg, utils)` (which returns `""` for the unnamed package) with plain old `pkg.getQualifiedName().toString()` (which returns an empty string for the unnamed package.) > > There's some minor localized cleanup and rearrangement as well. > > The test verifies behavior without and then with a source path, since that is the likely path of discovery by a user playing with the unnamed package. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: address review feedback ------------- Changes: - all: https://git.openjdk.java.net/jdk/pull/8708/files - new: https://git.openjdk.java.net/jdk/pull/8708/files/125474be..ccfb80b7 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=8708&range=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=8708&range=00-01 Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.java.net/jdk/pull/8708.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8708/head:pull/8708 PR: https://git.openjdk.java.net/jdk/pull/8708 From jjg at openjdk.java.net Tue May 17 00:18:07 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 17 May 2022 00:18:07 GMT Subject: RFR: JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section [v2] In-Reply-To: References: Message-ID: > As described in the JBS issue, the observed problem is a side-effect of a related but different issue, which is that record classes are not treated the same was as enum classes when it comes to generating the class hierarchy in `ClassTree`. Because record classes are not treated specially/differently, they are treated as ordinary/plain classes, with the side-effect that the page for `java.lang.Record` shows `Direct Known Subclasses`. > > The underlying fix is therefore to clone the enum support in `ClassTree` and related classes, to provide support for record classes. It is possible to do an extreme minimal clone, but that just clones some of the messy evolution already there. Instead, the code in `ClassTree` and its clients is refactored and modernized. > > Previously there were four explicit pairs of member fields, containing data for different groups (hierarchies) of classes, namely: plain classes, enum classes, interfaces and annotation interfaces. These fields are most of the code to support them are moved into some new abstractions to encapsulate related functionality. > > 1. The main new abstraction in `ClassTree` is `Hierarchy` which provides the support for the different hierarchies displayed in the generated pages. > 2. A new enum `HierarchyKind` identifies the four existing hierarchies (listed above) and now a new one, for record classes. The hierarchies correspond to the different kinds of declared type. > 3. A small new class `SubtypeMap` which is a multi-map for mapping a type element to its subtypes. This is used in `Hierarchy` and to record the classes that implement an interfaces. > > Generally, the naming should be clearer and more obvious. The most confusing name in the old code was `enumSubtypes` which was weird because enum classes don't have subtypes. It meant "subtypes of supertypes of enum classes". This was a prime motivator to switch to the `hierarchy` terminology. The variant spellings of `intfacs` have all been replaced by `interfaces`, and `classtree` becomes `classTree`. > > *Testing*: a new test case has been added to the `TestRecordTypes.java` test, which verifies the new record hierarchy is displayed on a a package tree page. It is not simple to directly test the observed/reported behavior, because it is specific to the JDK API documentation, and because it is about the content of the `java.lang.Record` API page. However, manual inspection and diff comparison between JDK API documentation generated before and after this change reveals only expected differences. These differences are on the `java.lang.R4cord` page (where the offending section is no longer displayed) and on the pages related to the two existing records in JDK ... which are now listed in `Record Class Hierarchy` sections in the appropriate `package-tree.html` files. Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains three commits: - merge with upstream master - fix copyright; update test description - JDK-8285939: javadoc java.lang.Record should not have "Direct Known Subclasses:" section ------------- Changes: https://git.openjdk.java.net/jdk/pull/8523/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=8523&range=01 Stats: 440 lines in 11 files changed: 141 ins; 131 del; 168 mod Patch: https://git.openjdk.java.net/jdk/pull/8523.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/8523/head:pull/8523 PR: https://git.openjdk.java.net/jdk/pull/8523 From jjg at openjdk.java.net Tue May 17 02:56:37 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 17 May 2022 02:56:37 GMT Subject: RFR: JDK-8284367: JQuery UI upgrade from 1.12.1 to 1.13.1 In-Reply-To: References: Message-ID: <3GurqKOIuQUgHCjQikZNZbVhOzkgy1eUR3rolGHwY9k=.10d16d7d-20a9-4142-ab2a-f12db36daa48@github.com> On Fri, 13 May 2022 13:49:21 GMT, Hannes Walln?fer wrote: > This updates jQuery UI (which is used for the javadoc in-age search feature) to version 1.13.1. > > Rendered documentation is available here: > http://cr.openjdk.java.net/~hannesw/8284367/api.00/ > > I noticed that we are carrying a lot of files from the jQuery UI distribution that we don't really need. this includes the jquery-ui.structure.css files (both minified and non-minified) as well as the icon image files. These files are not used or referenced anywhere in our generated documentation so I removed them instead of updating them. > > I also decided to update to the unthemed jQuery UI version as wee don't really use the theme. > > Some minor changes in our stylesheets were required to avoid unwanted layout changes: > > - Add a definition for 1px border around the selelcted list item in our jquery-ui.overrides CSS file. Without this, the the new jQuery UI would display a blue border or no border at all depending on the theme. The border is now orange so it is not distinguishable from the selected background, but it is necessary to keep the item in the same position when it is selected. > - Remove the `font-size: 13px` property from the `.result-item` class. This was necessary because previously this class used `font-family: Verdana` from the jQuery UI theme which looks bigger and is also inconsistent with the fonts we use in the rest of the page. Now that the search result list uses the same fonts as the rest of the page we can go back to using the inherited font size. I left the `font-size` property and changed the value to `inherit` because our tests don't like CSS classes that are not present in the stylesheet. > - Finally I had to add a property to the `ul.ui-autocomplete` list to explicitly set the background to white. The update made the background transparent. I'm not sure if this is a result of the missing theme but it was simple enough to fix. nice to see unnecessary files removed. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/8702 From jjg at openjdk.java.net Tue May 17 03:00:40 2022 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Tue, 17 May 2022 03:00:40 GMT Subject: RFR: JDK-8268335: Find better way to exclude empty HTML elements [v7] In-Reply-To: References: Message-ID: On Thu, 14 Apr 2022 12:42:11 GMT, Hannes Walln?fer wrote: >> Please review a change to straighten out the mechanism to avoid generating empty HTML elements in javadoc. >> >> Currently this is implemented using the `Content.isValid()` method in `HtmlTree.add(Content)` to check whether the the content argument should be added or dropped. This seems wrong since we don't really want to check for validity but non-emptiness (we want to drop empty elements, not print a warning or error). >> >> So the first decision was to get rid of the `Content.isValid()` method and use `Content.isEmpty()` instead. I considered keeping `isValid()` and using it to actually do some validation checks, but in the end decided it didn't make much sense and scrapped the method. >> >> My initial approach was to take care of emptiness at the content creation site, but it soon turned out there are too many sites potentially creating empty content. After fixing 40+ sites using a new `Content.addNonEmpty(Content)` method I still got empty elements that shouldn't be there in the JDK documentation. >> >> Therefore `HtmlTree.add(Content)` still checks for and drops empty content arguments. Instead, I added a new `HtmlTree.addUnchecked(Content)` method that adds the argument without the checks. The new method is only used 5 times in the whole codebase. It replaces the use of the special `HtmlTree.EMPTY` content token which is no longer needed. >> >> A few remarks about the rewritten `HtmlTree.isEmpty()` method: its purpose is to determine whether content is missing in an element that should have content. It therefore always returns `false` for elements that are expected or allowed to be without content. This is maybe a bit counter-intuitive, but it is what is needed. We could do a combined check such as `isVoid() || !isEmpty()` but that would still leave out elements that *can* be empty, such as `