From hannesw at openjdk.org  Mon Mar  3 15:05:35 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 3 Mar 2025 15:05:35 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v4]
In-Reply-To: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
Message-ID: <wqo9G8L9weUv8oxdwIWbrhk2ougiEIu27XREC4lPtjk=.c8c5f035-a6c2-4ac2-8968-7569f262a9c9@github.com>

> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
> 
> List of changes:
> 
>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>  - Fix font size and line height inconsistencies in many places.
>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>  - Add a subtle gray background to code elements in normal text to set them apart.
>  - Highlight headings of member details when they are used as link targets.
>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>  - Improve styling of additional HTML files in `doc-files` directories.
>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>  - Various cleanup.
> 
> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
> 
> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).

Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:

 - Changes:
    - Adjust subnav link color to meet WCAG contrast rules
    - Use subnav color for captions with links to meet WCAG rules
    - Make table header work with new caption color
    - Adjust some gaps
 - Changes:
    - Bring back breadcrumb highlight for current element
    - Use default tab color for search page caption

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23678/files
  - new: https://git.openjdk.org/jdk/pull/23678/files/817dcb00..7e301b70

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23678&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23678&range=02-03

  Stats: 60 lines in 4 files changed: 31 ins; 14 del; 15 mod
  Patch: https://git.openjdk.org/jdk/pull/23678.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23678/head:pull/23678

PR: https://git.openjdk.org/jdk/pull/23678

From hannesw at openjdk.org  Mon Mar  3 16:48:38 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 3 Mar 2025 16:48:38 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted text
Message-ID: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>

Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.

This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 

The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 

If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 

Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.

[1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element

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

Commit messages:
 - Make sure whitespace normalization is only applied to block content
 - Only normalize inside <pre> tags, add tests
 - 8346118: Improve whitespace normalization in preformatted text

Changes: https://git.openjdk.org/jdk/pull/23868/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23868&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8346118
  Stats: 334 lines in 11 files changed: 258 ins; 0 del; 76 mod
  Patch: https://git.openjdk.org/jdk/pull/23868.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23868/head:pull/23868

PR: https://git.openjdk.org/jdk/pull/23868

From liach at openjdk.org  Mon Mar  3 17:16:54 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 3 Mar 2025 17:16:54 GMT
Subject: RFR: 8345555: Improve layout of search results [v2]
In-Reply-To: <4jq45fp2d8Myti_6nTFUu0DGViGykRjSpgM-oh3f4MQ=.ccd20a64-1bbe-44f6-ab54-429121e08ca4@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <4jq45fp2d8Myti_6nTFUu0DGViGykRjSpgM-oh3f4MQ=.ccd20a64-1bbe-44f6-ab54-429121e08ca4@github.com>
Message-ID: <utOEuFQfNEdakcrGPOVd0dBZuIlnatYPuW4pHQMJ-jY=.82a7218d-c694-4511-aab2-7a9eea1ce6e0@github.com>

On Mon, 17 Feb 2025 19:54:49 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
>> 
>> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.02/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>> 
>> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>> 
>> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>> 
>> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
>> 
>> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>> 
>> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to ...
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Rename label property as it has special meaning to jquery-ui

Seems fine; @nizarbenalla please review too.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexWriter.java line 263:

> 261:             case SYSTEM_PROPERTY -> "doclet.System_property_in";
> 262:             case SECTION -> "doclet.Section_in";
> 263:             case EXTERNAL_SPEC-> "doclet.External_specification_in";

Suggestion:

            case EXTERNAL_SPEC -> "doclet.External_specification_in";

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexItem.java line 127:

> 125:          * {@return the kind of index item for a program element}
> 126:          */
> 127:         public static Kind ofElement (Element elem, Utils utils) {

Suggestion:

        public static Kind ofElement(Element elem, Utils utils) {

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

PR Review: https://git.openjdk.org/jdk/pull/23666#pullrequestreview-2654746323
PR Review Comment: https://git.openjdk.org/jdk/pull/23666#discussion_r1977880767
PR Review Comment: https://git.openjdk.org/jdk/pull/23666#discussion_r1977885842

From liach at openjdk.org  Mon Mar  3 17:20:59 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 3 Mar 2025 17:20:59 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
Message-ID: <7cDq6kmPLqIHPEis_BwPdAdGEFdG076hJ8g37xELRJc=.b02df83f-e6de-4b8e-adb9-aabb1bb0d05c@github.com>

On Fri, 28 Feb 2025 15:13:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add @bug id to tests

Looks fine. @nizarbenalla please check out too.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23777#pullrequestreview-2654763443

From weijun at openjdk.org  Mon Mar  3 17:34:55 2025
From: weijun at openjdk.org (Weijun Wang)
Date: Mon, 3 Mar 2025 17:34:55 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
Message-ID: <ZgkOpYFmGO9ws0K1_7oySSQXThxP3PuHakON-qNedBE=.c590fb66-fcd2-497d-840a-0f6d50339aed@github.com>

On Fri, 28 Feb 2025 15:13:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add @bug id to tests

The keyboard shortcuts are great! However, I don't quite get what "be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly" means. If I press the up/down keys I can see the right side is scrolling (in a constant speed) and whatever section shows up is highlighted on the left side. How do I navigate to a section quickly? I thought you meant every down key press will jump to the next section.

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

PR Comment: https://git.openjdk.org/jdk/pull/23777#issuecomment-2695094462

From hannesw at openjdk.org  Mon Mar  3 19:10:16 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 3 Mar 2025 19:10:16 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: <ZgkOpYFmGO9ws0K1_7oySSQXThxP3PuHakON-qNedBE=.c590fb66-fcd2-497d-840a-0f6d50339aed@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
 <ZgkOpYFmGO9ws0K1_7oySSQXThxP3PuHakON-qNedBE=.c590fb66-fcd2-497d-840a-0f6d50339aed@github.com>
Message-ID: <Sz--I4f32nGfFWmRb96UIbKBpU92JNHE_JMg52ZpGZ4=.c06e16ea-3702-49fa-90e4-37991e7f2920@github.com>

On Mon, 3 Mar 2025 17:32:03 GMT, Weijun Wang <weijun at openjdk.org> wrote:

> The keyboard shortcuts are great! However, I don't quite get what "be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly" means. If I press the up/down keys I can see the right side is scrolling (in a constant speed) and whatever section shows up is highlighted on the left side. How do I navigate to a section quickly? I thought you meant every down key press will jump to the next section.

Sorry for being imprecise, what I meant was this: 

 - type something in the left side "Filter" input
 - press tab or arrow-down key to move focus to the first item in the list
 - optionally navigate with tab/shift-tab/arrow keys to the list item of choice
 - hit enter to go to the item and reset the filter input

So the only way to get the orange highlight that can be moved by tab/arrow keys is via tabbing/arrowing out of the filter input box. That's because this is the keyboard focus, which can't be set by mouse/trackpad.

Unfortunately Safari has a bug where the focus sometimes does not show when pressing arrow-down from the filter input, but tab should always work. The bug has already been fixed and will hopefully be in the released version soon.

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

PR Comment: https://git.openjdk.org/jdk/pull/23777#issuecomment-2695303284

From weijun at openjdk.org  Mon Mar  3 19:52:57 2025
From: weijun at openjdk.org (Weijun Wang)
Date: Mon, 3 Mar 2025 19:52:57 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
Message-ID: <-7M_izw-cqtiUm-cwXCytLXJBVXFhEW91Ekt0uTab3o=.36c2bdd4-c2e1-49be-84d4-7cfea47847ba@github.com>

On Fri, 28 Feb 2025 15:13:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add @bug id to tests

Wow, that?s neat! Sorry, I should have played around with it a bit more before asking.

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

PR Comment: https://git.openjdk.org/jdk/pull/23777#issuecomment-2695391508

From hannesw at openjdk.org  Mon Mar  3 19:55:42 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 3 Mar 2025 19:55:42 GMT
Subject: RFR: 8345555: Improve layout of search results [v3]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <AF3RVS4Osqi8Aff67R_0x-bQfY1EKRY8y9ublT7p-_Q=.ebd8e45c-6586-46be-9dc7-aaa26b2767b8@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.02/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with three additional commits since the last revision:

 - Review feedback (formatting)
 - Remove counterproductive restriction in search pattern
 - Fix search menu selecting item at current mouse position

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/48a70635..65de882c

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=01-02

  Stats: 23 lines in 3 files changed: 6 ins; 7 del; 10 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From hannesw at openjdk.org  Mon Mar  3 20:08:53 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 3 Mar 2025 20:08:53 GMT
Subject: RFR: 8345555: Improve layout of search results [v2]
In-Reply-To: <utOEuFQfNEdakcrGPOVd0dBZuIlnatYPuW4pHQMJ-jY=.82a7218d-c694-4511-aab2-7a9eea1ce6e0@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <4jq45fp2d8Myti_6nTFUu0DGViGykRjSpgM-oh3f4MQ=.ccd20a64-1bbe-44f6-ab54-429121e08ca4@github.com>
 <utOEuFQfNEdakcrGPOVd0dBZuIlnatYPuW4pHQMJ-jY=.82a7218d-c694-4511-aab2-7a9eea1ce6e0@github.com>
Message-ID: <F_iOJ6Gg0kyKqO36-DzT0IQLvAvj5CqNjaz9cuvKyMQ=.dc6abe94-61d3-4f59-b9d2-797489858ca8@github.com>

On Mon, 3 Mar 2025 17:14:07 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Rename label property as it has special meaning to jquery-ui
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexItem.java line 127:
> 
>> 125:          * {@return the kind of index item for a program element}
>> 126:          */
>> 127:         public static Kind ofElement (Element elem, Utils utils) {
> 
> Suggestion:
> 
>         public static Kind ofElement(Element elem, Utils utils) {

Thanks, @liach! I pushed the changes you suggested along with two small fixes.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23666#discussion_r1978124216

From liach at openjdk.org  Tue Mar  4 02:16:57 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 4 Mar 2025 02:16:57 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v4]
In-Reply-To: <wqo9G8L9weUv8oxdwIWbrhk2ougiEIu27XREC4lPtjk=.c8c5f035-a6c2-4ac2-8968-7569f262a9c9@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
 <wqo9G8L9weUv8oxdwIWbrhk2ougiEIu27XREC4lPtjk=.c8c5f035-a6c2-4ac2-8968-7569f262a9c9@github.com>
Message-ID: <HMWY7401-UmzQ0Px_wJvu024Wfs9g3LDi9O5aD74R74=.5edd6c52-64b8-4392-a277-5a367fde65a4@github.com>

On Mon, 3 Mar 2025 15:05:35 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
>> 
>> List of changes:
>> 
>>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>>  - Fix font size and line height inconsistencies in many places.
>>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>>  - Add a subtle gray background to code elements in normal text to set them apart.
>>  - Highlight headings of member details when they are used as link targets.
>>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>>  - Improve styling of additional HTML files in `doc-files` directories.
>>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>>  - Various cleanup.
>> 
>> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
>> 
>> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).
>
> Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Changes:
>     - Adjust subnav link color to meet WCAG contrast rules
>     - Use subnav color for captions with links to meet WCAG rules
>     - Make table header work with new caption color
>     - Adjust some gaps
>  - Changes:
>     - Bring back breadcrumb highlight for current element
>     - Use default tab color for search page caption

Looks good. @nizarbenalla for a look too.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23678#pullrequestreview-2655750579

From liach at openjdk.org  Tue Mar  4 02:17:55 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 4 Mar 2025 02:17:55 GMT
Subject: RFR: 8349369:
 test/docs/jdk/javadoc/doccheck/checks/jdkCheckLinks.java did not report on
 missing man page files
In-Reply-To: <FGRL-t_YxCu4RIX0Qhcm-14n7TF76On2Rgp7XV4CvXc=.e1fa38df-e846-4734-a3ad-1f3bb2145afc@github.com>
References: <XFGYLVCil0or1A5UwmBxnFl0d4SpVZ7fWbcxVN6yGHk=.2d6ec2b6-7b2b-450a-aede-881cb7b033d5@github.com>
 <FGRL-t_YxCu4RIX0Qhcm-14n7TF76On2Rgp7XV4CvXc=.e1fa38df-e846-4734-a3ad-1f3bb2145afc@github.com>
Message-ID: <ISt7d8gEHaqziR9bhIPXmPMPy6QdVQBEIDTqgnhwygU=.e10e0ef2-34b2-4462-86be-f08626b642c1@github.com>

On Tue, 18 Feb 2025 17:11:33 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review this small update to make the test more robust, the test did not always check links to other files if they did not contain a fragment or a `#`symbol.
>> 
>> I'd like to add that the original [doccheck](https://github.com/openjdk/doccheck) also didn't pick up on these missing files when I ran it. 
>> 
>> TIA
>
> test/docs/jdk/javadoc/doccheck/doccheckutils/checkers/LinkChecker.java line 227:
> 
>> 225:                 && missingFiles == 0
>> 226:                 && badSchemes == 0
>> 227:                 && log.noErrors();
> 
> So we have both these counters and the `log` instance to track errors. Shouldn't the `missingIds` counter have bee increased when the error was logged?

Indeed, would be much better if we can just check `log.noErrors()`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23441#discussion_r1978498602

From hannesw at openjdk.org  Tue Mar  4 15:33:16 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 4 Mar 2025 15:33:16 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v3]
In-Reply-To: <aPc5o3JwcIT36U76Kld8QVmbYn48y31mqSPA5W4SVZM=.28efc778-9f95-4729-9789-ca884494625f@github.com>
References: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
 <RiN6eY394H2GHlN5EGwBLHY7YkU0ldGxy9metmzGKXw=.8193eeee-9802-4d46-8ab9-06ec372b6d71@github.com>
 <YU3Igwg3JIqDERADTzTuq2MxXOwbB20kSqwbE8PKcfY=.d9d0ff36-6f22-4ecb-84a4-6492d8b1679a@github.com>
 <H2H47ZzNMqq1v8YRP5Zo8J1_GQs8YtBbypWzYl1B_wo=.ac6a0feb-a66c-49e4-bfb1-2c9200f0fd73@github.com>
 <aPc5o3JwcIT36U76Kld8QVmbYn48y31mqSPA5W4SVZM=.28efc778-9f95-4729-9789-ca884494625f@github.com>
Message-ID: <J23FkKD85POsXIxtVD-5jRUd8cX4xHsIrBucHMqJI1E=.f1bb4549-6c57-47eb-a644-baa4aed3d6ba@github.com>

On Wed, 26 Feb 2025 20:16:36 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> `jpackage` and `jar` return 0 if there are no args. `javap` returns `2`/`EXIT_CMDERR` so it's not very consistent.
>> 
>> This is the behavior when returning `CMDERR`
>> 
>> 
>> nizar-mac! $ javadoc 
>> error: Usage:
>>       javadoc [options] [packagenames] [sourcefiles] [@files]
>>   For more details on available options, use --help or --help-extra
>> 1 error
>> 
>> 
>> I'm not sure we want to emit an error? Returning 0 or 1 might better.
>> But I can understand why we would want to keep those things the same.
>
> For the record, I discussed this offline with a couple of people.
> Since the user didn't ask for the help message, this is indeed be an invalid run and returning a non-zero value might  be the right thing to do.

I see, you can't return an error without generating the `error: ` prefix and the `1 error` line. That's a pity, as the `error: Usage:` line makes no sense, because the usage message is not an error message. An acceptable solution could be to print the usage method, and then throw the original error message, which produces:


Usage:
    javadoc [options] [packagenames] [sourcefiles] [@files]
For more details on available options, use --help or --help-extra
error: No modules, packages or classes specified.
1 error

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23618#discussion_r1979693905

From jjg at openjdk.org  Wed Mar  5 18:09:53 2025
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 5 Mar 2025 18:09:53 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted
 text
In-Reply-To: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
Message-ID: <ytiC5aoARrCzdFLE1X3jpB4mTEDRrZwcC2Vs6mNnZwo=.f8783235-5734-4fd0-8bc2-4f2b2da0e91b@github.com>

On Mon, 3 Mar 2025 16:41:18 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
> 
> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
> 
> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
> 
> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
> 
> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
> 
> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element

As you indicated, there are two problems being addressed here, which might indicate the need for two separate patches. These issues are:

1. The leading 1-space problem.
2. The trailing newline-after-<pre> problem

For the first, it is unduly hard work to fix this just for `<pre>` blocks. I still think that an overall better long-term solution would be to apply a conceptual `stripIndent` to the entire doc comment. This would bring traditional comments into line with the new Markdown comments, and can be done in just a few lines in `DocCommentParser`, and doing it there in DCP means you need not update `Elements.getDocComment`. If nothing else, I would suggest doing the experiment and comparing the generated docs, to verify there are no unexpected side effects. If there are any significant unexpected side effects, then your approach might deserve a second look. You could also make this a JDK-version-specific change if you wanted: meaning the new behavior does not apply to older JDK versions, although that is not a policy we have adhered to in the past.

For the second, I just feel that is a step too far, using JavaScript to clean up what some might consider to be bad input. Authors should either write HTML according to the HTML (and CSS?) specs, so that `javadoc` is just a "pass-through" layer, or authors should use a suitable construct, like `{@snippet...}`, that is "pleasing" to look at in source form while still generating the desired output.

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

PR Comment: https://git.openjdk.org/jdk/pull/23868#issuecomment-2701699839

From hannesw at openjdk.org  Wed Mar  5 20:48:57 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 5 Mar 2025 20:48:57 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted
 text
In-Reply-To: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
Message-ID: <us5X438kN5v90INayXaRbxewu5dy8VUOstKdxJyYa8U=.ff7fa06e-bf19-4bc7-888d-25b406df60e5@github.com>

On Mon, 3 Mar 2025 16:41:18 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
> 
> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
> 
> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
> 
> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
> 
> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
> 
> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element

Thanks for reviewing this, Jon. I agree there are two issues that maybe shold be handled separately. 

Regarding the first issue, stripping leading space in `DocCommentParser`, I did in fact start out processing the whole doc comment. I was pretty far into fixing tests when I realized that this approach breaks our ability to get a diagnostic position from a string extracted from the comment. The source postion mapping is generated in `JavadocScanner`, and it would be quite complex to keep track of whitespace removed after the fact and correctly translate to a source position. 

The test that made me realize this problem was [TestDocTreeDiags.java], which tests reporting positions inside strings extracted from the comment (added in [JDK-8268420]) , but with wholesale whitespace removal also start positions are affected. I should have mentioned this in the PR description, but it was already long enough as it was.

[TestDocTreeDiags.java]: https://github.com/openjdk/jdk/blob/master/test/langtools/jdk/javadoc/doclet/testDocTreeDiags/TestDocTreeDiags.java
[JDK-8268420]: https://bugs.openjdk.org/browse/JDK-8268420

This is why I reverted to the proposed minimalistic solution, limiting space removal to text and `{@code}`/`{@literal}` tags within `<pre>` elements. These are all doctrees that are passed though without further processing, so it is highly unlikely that anybody would ever want to report a source position inside of them. The begin postions will be correct since we're parsing the unchanged doc comment, but positions inside the string after the first line break would report a wrong position. This is why I filed [a CSR to amend the spec for above mentioned method][CSR] with a note about this. 

[CSR]: https://bugs.openjdk.org/browse/JDK-8350428

Regarding the second issue, I agree the JavaScript solution is not ideal. But it's a small price to pay in order to get readable and good looking documentation. We have close to 1000 instances of `<pre>{@code}` in JDK source code alone, and they will never get fixed and continue to haunt our otherwise great documentation. The same problem affects most Java libraries out there. You see I'm quite passionate about this, but I agree to move it to a separate issue if you think that's the best way to handle this.

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

PR Comment: https://git.openjdk.org/jdk/pull/23868#issuecomment-2702033467

From hannesw at openjdk.org  Thu Mar  6 05:18:26 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 6 Mar 2025 05:18:26 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted
 text [v2]
In-Reply-To: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
Message-ID: <LYiVL3onbfc3beZkP2PyJqqysTzqQng1At6f3gNoTb4=.dc92b07d-b6e1-445e-b26a-eca897bd9f48@github.com>

> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
> 
> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
> 
> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
> 
> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
> 
> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
> 
> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Remove script for normalizing leading space in pre/code based on review feedback

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23868/files
  - new: https://git.openjdk.org/jdk/pull/23868/files/13638f80..d2128b3a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23868&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23868&range=00-01

  Stats: 9 lines in 1 file changed: 0 ins; 9 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/23868.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23868/head:pull/23868

PR: https://git.openjdk.org/jdk/pull/23868

From hannesw at openjdk.org  Thu Mar  6 05:31:52 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 6 Mar 2025 05:31:52 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted
 text [v2]
In-Reply-To: <LYiVL3onbfc3beZkP2PyJqqysTzqQng1At6f3gNoTb4=.dc92b07d-b6e1-445e-b26a-eca897bd9f48@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
 <LYiVL3onbfc3beZkP2PyJqqysTzqQng1At6f3gNoTb4=.dc92b07d-b6e1-445e-b26a-eca897bd9f48@github.com>
Message-ID: <RB6nVg-TnIJnBSM27dVYhhV-cu-de_fjlAqxIZSSZhw=.5d807de3-b5ca-447e-8c8e-8e0aa775da97@github.com>

On Thu, 6 Mar 2025 05:18:26 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
>> 
>> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
>> 
>> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
>> 
>> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
>> 
>> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
>> 
>> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Remove script for normalizing leading space in pre/code based on review feedback

I removed the script to strip leading whitespace based on your feedback. 

Regarding the added complexity this patch adds to `DocCommentParser` (which I dislike as you do): I think we could reconsider exclusion of multiline inline content. The test examples I came up with are very contrived (multiline `title` attribute and `{@index}` tag inside `<pre>`, both of which would not mind removal of redundant space after line breaks). I initially tried using a `{@snippet}` tag inside `<pre>` which is also completely unrealistic, but `{@snippet}` is not even affected as it does its own parsing.

Without that exclusion, the patch is mostly just two simple methods, and all the added complexity to `content` and other existing methods is gone.

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

PR Comment: https://git.openjdk.org/jdk/pull/23868#issuecomment-2702853308

From nbenalla at openjdk.org  Thu Mar  6 10:52:53 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Thu, 6 Mar 2025 10:52:53 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
Message-ID: <Gk6lavVK_0TRI8LyeZHzJFV519EkeY8fPwHI0Y4NpaE=.bef22566-6a68-4663-ab68-82b42b63821b@github.com>

On Fri, 28 Feb 2025 15:13:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add @bug id to tests

Code looks fine, the keyboard navigation is great!

Question: for TOC navigation, should the navigation using tab/shift-tab be documented as well? Or maybe mentioning the fact you need to first focus on the input field for it to work.

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

PR Review: https://git.openjdk.org/jdk/pull/23777#pullrequestreview-2664071923

From nbenalla at openjdk.org  Thu Mar  6 12:10:04 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Thu, 6 Mar 2025 12:10:04 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v4]
In-Reply-To: <wqo9G8L9weUv8oxdwIWbrhk2ougiEIu27XREC4lPtjk=.c8c5f035-a6c2-4ac2-8968-7569f262a9c9@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
 <wqo9G8L9weUv8oxdwIWbrhk2ougiEIu27XREC4lPtjk=.c8c5f035-a6c2-4ac2-8968-7569f262a9c9@github.com>
Message-ID: <y_RGYDFItA1vbphu9SGwE-RnaKkX0JHeTtW9L4JN3eI=.9e49cb52-fd39-4ba5-823f-b65f8721648a@github.com>

On Mon, 3 Mar 2025 15:05:35 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
>> 
>> List of changes:
>> 
>>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>>  - Fix font size and line height inconsistencies in many places.
>>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>>  - Add a subtle gray background to code elements in normal text to set them apart.
>>  - Highlight headings of member details when they are used as link targets.
>>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>>  - Improve styling of additional HTML files in `doc-files` directories.
>>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>>  - Various cleanup.
>> 
>> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
>> 
>> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).
>
> Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Changes:
>     - Adjust subnav link color to meet WCAG contrast rules
>     - Use subnav color for captions with links to meet WCAG rules
>     - Make table header work with new caption color
>     - Adjust some gaps
>  - Changes:
>     - Bring back breadcrumb highlight for current element
>     - Use default tab color for search page caption

I left a couple of comments, but they are not a blocker for this PR.
Our stylesheet is quite large so we might want to consider running a linter on it in the future.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css line 827:

> 825:     font-size: inherit;
> 826: }
> 827: code {

I noticed there is a duplicate `code` selector (first used in line 162), is this intentional?
I also think it's odd to have `code` after `:is(h1, h2, h3, h4, h5, h6, sup, sub, small, big) code`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css line 1537:

> 1535:     }
> 1536: }
> 1537: pre {

Duplicate selector, It doesn't have the same fields as the one from line 129

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

PR Review: https://git.openjdk.org/jdk/pull/23678#pullrequestreview-2664235129
PR Review Comment: https://git.openjdk.org/jdk/pull/23678#discussion_r1983234865
PR Review Comment: https://git.openjdk.org/jdk/pull/23678#discussion_r1983231137

From hannesw at openjdk.org  Thu Mar  6 16:42:42 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 6 Mar 2025 16:42:42 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted
 text [v3]
In-Reply-To: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
Message-ID: <bA344QY2QtBR5YdGkCCRqW3PMl8_iT5x59hfk8SzI28=.97b22bfb-8817-4f61-9238-2ab3e9c4c290@github.com>

> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
> 
> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
> 
> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
> 
> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
> 
> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
> 
> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Switch to post-processing approach that fixes both problems
  
  This implements a visitor-based post-processing method in
  DocCommentParser that is able to fix both kinds of whitespace
  common in traditional doc comments. Tests have to be adapted
  to the additional normalization step. A few more tests should
  be added on the javadoc side.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23868/files
  - new: https://git.openjdk.org/jdk/pull/23868/files/d2128b3a..8a9036d6

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23868&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23868&range=01-02

  Stats: 304 lines in 4 files changed: 200 ins; 63 del; 41 mod
  Patch: https://git.openjdk.org/jdk/pull/23868.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23868/head:pull/23868

PR: https://git.openjdk.org/jdk/pull/23868

From hannesw at openjdk.org  Thu Mar  6 16:54:13 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 6 Mar 2025 16:54:13 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted
 text [v4]
In-Reply-To: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
Message-ID: <FkV3_9PYJ9-3DIjOM1tLbeA9_6IxIzmYkAakXsvLulA=.2bba9cb0-a474-4716-96c9-a0b41b3a3b40@github.com>

> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
> 
> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
> 
> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
> 
> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
> 
> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
> 
> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Fix comment

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23868/files
  - new: https://git.openjdk.org/jdk/pull/23868/files/8a9036d6..69464173

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23868&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23868&range=02-03

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/23868.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23868/head:pull/23868

PR: https://git.openjdk.org/jdk/pull/23868

From hannesw at openjdk.org  Fri Mar  7 07:41:58 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 7 Mar 2025 07:41:58 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: <Gk6lavVK_0TRI8LyeZHzJFV519EkeY8fPwHI0Y4NpaE=.bef22566-6a68-4663-ab68-82b42b63821b@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
 <Gk6lavVK_0TRI8LyeZHzJFV519EkeY8fPwHI0Y4NpaE=.bef22566-6a68-4663-ab68-82b42b63821b@github.com>
Message-ID: <C3iwcMxFd8rNAzFrGiBWQy2Eza8mE_sG4ZE6hpfNkQw=.6e805ce1-64f7-451b-9010-c1172e901afd@github.com>

On Thu, 6 Mar 2025 10:50:29 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Question: for TOC navigation, should the navigation using tab/shift-tab be documented as well? Or maybe mentioning the fact you need to first focus on the input field for it to work.

Good point, I'll update the help text to include the tab key. I will also add an item for left/right arrow keys to switch between table tabs.

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

PR Comment: https://git.openjdk.org/jdk/pull/23777#issuecomment-2705742669

From hannesw at openjdk.org  Fri Mar  7 08:23:27 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 7 Mar 2025 08:23:27 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v7]
In-Reply-To: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
Message-ID: <CR-6rdexATAutG52i0updQHYsLlE41BEMdVuDtoV9lg=.73853d22-8488-474a-8b2a-ca666f455c9c@github.com>

> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
> 
>  - <kbd>/</kbd> to switch focus to the search input
>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
> 
> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
> 
> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
> 
> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
> 
> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
> 
> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Improve keyboard navigation help section

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23777/files
  - new: https://git.openjdk.org/jdk/pull/23777/files/b19d43f2..0bac1ec7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23777&range=06
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23777&range=05-06

  Stats: 15 lines in 2 files changed: 4 ins; 1 del; 10 mod
  Patch: https://git.openjdk.org/jdk/pull/23777.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23777/head:pull/23777

PR: https://git.openjdk.org/jdk/pull/23777

From hannesw at openjdk.org  Fri Mar  7 08:23:27 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 7 Mar 2025 08:23:27 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: <Gk6lavVK_0TRI8LyeZHzJFV519EkeY8fPwHI0Y4NpaE=.bef22566-6a68-4663-ab68-82b42b63821b@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <ONSqKmv7pTrQOLexozn0xGQETn706hYxd8g3EimpskA=.1bba85e3-4db1-4131-a10b-475ddd760f47@github.com>
 <Gk6lavVK_0TRI8LyeZHzJFV519EkeY8fPwHI0Y4NpaE=.bef22566-6a68-4663-ab68-82b42b63821b@github.com>
Message-ID: <dC--RbGO-VBPMNAp5OlUnET8iQMFCSylJsXd6vmOfww=.455b7726-261e-44c8-9ea7-750ec97f0766@github.com>

On Thu, 6 Mar 2025 10:50:29 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Add @bug id to tests
>
> Code looks fine, the keyboard navigation is great!
> 
> Question: for TOC navigation, should the navigation using tab/shift-tab be documented as well? Or maybe mentioning the fact you need to first focus on the input field for it to work.

I improved the help section based on @nizarbenalla's feedback, also making list items shorter and more uniform. This is how it looks now:

![grafik](https://github.com/user-attachments/assets/c3b10440-87b3-4f46-8cf1-61a62001069b)

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

PR Comment: https://git.openjdk.org/jdk/pull/23777#issuecomment-2705814231

From hannesw at openjdk.org  Fri Mar  7 08:33:42 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 7 Mar 2025 08:33:42 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v8]
In-Reply-To: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
Message-ID: <Qt8dP-SbUafQTWUCTCdZSgtoPb7qUWVSHvJ7Z2no9Io=.b8183e48-3307-4fce-8420-235d8f59d4c8@github.com>

> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
> 
>  - <kbd>/</kbd> to switch focus to the search input
>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
> 
> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
> 
> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
> 
> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
> 
> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
> 
> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Reverse down/up arrows

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23777/files
  - new: https://git.openjdk.org/jdk/pull/23777/files/0bac1ec7..f447ea6b

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23777&range=07
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23777&range=06-07

  Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/23777.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23777/head:pull/23777

PR: https://git.openjdk.org/jdk/pull/23777

From hannesw at openjdk.org  Fri Mar  7 08:44:08 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 7 Mar 2025 08:44:08 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v9]
In-Reply-To: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
Message-ID: <i6h5qrkXFqln_YEcxDVOShdbKc8Ie4mxA5sHcvB6qvs=.0a6d1f41-094a-44cf-bf43-c70f718c6fcf@github.com>

> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
> 
>  - <kbd>/</kbd> to switch focus to the search input
>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
> 
> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
> 
> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
> 
> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
> 
> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
> 
> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Wording

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23777/files
  - new: https://git.openjdk.org/jdk/pull/23777/files/f447ea6b..f39e20c7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23777&range=08
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23777&range=07-08

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/23777.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23777/head:pull/23777

PR: https://git.openjdk.org/jdk/pull/23777

From hannesw at openjdk.org  Fri Mar  7 09:20:31 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 7 Mar 2025 09:20:31 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v5]
In-Reply-To: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
Message-ID: <Sv_d2V0s64Qd29OlW1K4YyHYFiNbCV0S5BycupUD3UY=.b44363a2-3c0b-4329-9955-d6856ca3759d@github.com>

> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
> 
> List of changes:
> 
>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>  - Fix font size and line height inconsistencies in many places.
>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>  - Add a subtle gray background to code elements in normal text to set them apart.
>  - Highlight headings of member details when they are used as link targets.
>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>  - Improve styling of additional HTML files in `doc-files` directories.
>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>  - Various cleanup.
> 
> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
> 
> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Review feedback: merge duplicate selectors

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23678/files
  - new: https://git.openjdk.org/jdk/pull/23678/files/7e301b70..40599452

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23678&range=04
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23678&range=03-04

  Stats: 34 lines in 1 file changed: 15 ins; 19 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/23678.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23678/head:pull/23678

PR: https://git.openjdk.org/jdk/pull/23678

From hannesw at openjdk.org  Fri Mar  7 09:27:54 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 7 Mar 2025 09:27:54 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v4]
In-Reply-To: <y_RGYDFItA1vbphu9SGwE-RnaKkX0JHeTtW9L4JN3eI=.9e49cb52-fd39-4ba5-823f-b65f8721648a@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
 <wqo9G8L9weUv8oxdwIWbrhk2ougiEIu27XREC4lPtjk=.c8c5f035-a6c2-4ac2-8968-7569f262a9c9@github.com>
 <y_RGYDFItA1vbphu9SGwE-RnaKkX0JHeTtW9L4JN3eI=.9e49cb52-fd39-4ba5-823f-b65f8721648a@github.com>
Message-ID: <vQZE1ozUXegHoGpLJx8ftZYypVfTEqs8cwVCzLZS_Y0=.7122f07a-f6a6-445e-b980-096ffa49ab43@github.com>

On Thu, 6 Mar 2025 12:04:49 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Changes:
>>     - Adjust subnav link color to meet WCAG contrast rules
>>     - Use subnav color for captions with links to meet WCAG rules
>>     - Make table header work with new caption color
>>     - Adjust some gaps
>>  - Changes:
>>     - Bring back breadcrumb highlight for current element
>>     - Use default tab color for search page caption
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css line 827:
> 
>> 825:     font-size: inherit;
>> 826: }
>> 827: code {
> 
> I noticed there is a duplicate `code` selector (first used in line 162), is this intentional?
> I also think it's odd to have `code` after `:is(h1, h2, h3, h4, h5, h6, sup, sub, small, big) code`

I merged the duplicate selectors. 

The `:is(...) code` selector is to use inherited (natural) font size in places where our standard code font size is not appropriate, such as in headings or the ["Discussion" sections in j.l.invoke.MethodHandles](https://cr.openjdk.org/~hannesw/8344301/api.06/java.base/java/lang/invoke/MethodHandles.html#exactInvoker(java.lang.invoke.MethodType)). This wouldn't be necessary if we would use relative font size for code, but we want a constant size in most places (text, summary lists, block tags, signatures) which would be much harder to get with relative size.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23678#discussion_r1984728510

From nbenalla at openjdk.org  Fri Mar  7 11:41:54 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 7 Mar 2025 11:41:54 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v5]
In-Reply-To: <Sv_d2V0s64Qd29OlW1K4YyHYFiNbCV0S5BycupUD3UY=.b44363a2-3c0b-4329-9955-d6856ca3759d@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
 <Sv_d2V0s64Qd29OlW1K4YyHYFiNbCV0S5BycupUD3UY=.b44363a2-3c0b-4329-9955-d6856ca3759d@github.com>
Message-ID: <65xwl3LWVYKwc92Ju4nNBS-Igzra3hZtfQbSU1SXUFo=.c444f88e-71f7-480b-8fb5-a5e2d599970c@github.com>

On Fri, 7 Mar 2025 09:20:31 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
>> 
>> List of changes:
>> 
>>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>>  - Fix font size and line height inconsistencies in many places.
>>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>>  - Add a subtle gray background to code elements in normal text to set them apart.
>>  - Highlight headings of member details when they are used as link targets.
>>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>>  - Improve styling of additional HTML files in `doc-files` directories.
>>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>>  - Various cleanup.
>> 
>> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
>> 
>> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Review feedback: merge duplicate selectors

Looks good.

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/23678#pullrequestreview-2667014443

From nbenalla at openjdk.org  Fri Mar  7 12:10:53 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 7 Mar 2025 12:10:53 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v9]
In-Reply-To: <i6h5qrkXFqln_YEcxDVOShdbKc8Ie4mxA5sHcvB6qvs=.0a6d1f41-094a-44cf-bf43-c70f718c6fcf@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <i6h5qrkXFqln_YEcxDVOShdbKc8Ie4mxA5sHcvB6qvs=.0a6d1f41-094a-44cf-bf43-c70f718c6fcf@github.com>
Message-ID: <s1d42b1KY56DwF8x-V2ul-D0f0fNNDb8G_30rEcg-bY=.f52c49b5-dba5-42a4-a5b1-aa1daa41e411@github.com>

On Fri, 7 Mar 2025 08:44:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Wording

Thanks for updating the help text. Looks good.

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/23777#pullrequestreview-2667069550

From liach at openjdk.org  Fri Mar  7 20:42:56 2025
From: liach at openjdk.org (Chen Liang)
Date: Fri, 7 Mar 2025 20:42:56 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v5]
In-Reply-To: <Sv_d2V0s64Qd29OlW1K4YyHYFiNbCV0S5BycupUD3UY=.b44363a2-3c0b-4329-9955-d6856ca3759d@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
 <Sv_d2V0s64Qd29OlW1K4YyHYFiNbCV0S5BycupUD3UY=.b44363a2-3c0b-4329-9955-d6856ca3759d@github.com>
Message-ID: <QQEXy-vT2SIb9aCUQIt7WmDHM4lNywXcnYdPE1g32CM=.012cc82c-239e-4017-96cf-06e626cbf094@github.com>

On Fri, 7 Mar 2025 09:20:31 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
>> 
>> List of changes:
>> 
>>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>>  - Fix font size and line height inconsistencies in many places.
>>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>>  - Add a subtle gray background to code elements in normal text to set them apart.
>>  - Highlight headings of member details when they are used as link targets.
>>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>>  - Improve styling of additional HTML files in `doc-files` directories.
>>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>>  - Various cleanup.
>> 
>> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
>> 
>> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Review feedback: merge duplicate selectors

Looks good in a chromium browser.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23678#pullrequestreview-2668311862

From liach at openjdk.org  Fri Mar  7 20:47:53 2025
From: liach at openjdk.org (Chen Liang)
Date: Fri, 7 Mar 2025 20:47:53 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v9]
In-Reply-To: <i6h5qrkXFqln_YEcxDVOShdbKc8Ie4mxA5sHcvB6qvs=.0a6d1f41-094a-44cf-bf43-c70f718c6fcf@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <i6h5qrkXFqln_YEcxDVOShdbKc8Ie4mxA5sHcvB6qvs=.0a6d1f41-094a-44cf-bf43-c70f718c6fcf@github.com>
Message-ID: <RLw9VNqSOqLVbATR1obOmzAWc9voX7pi5JooK64_ykk=.49f27784-198a-4267-b75c-0dd8a2eb32c2@github.com>

On Fri, 7 Mar 2025 08:44:08 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Wording

Marked as reviewed by liach (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/23777#pullrequestreview-2668319702

From hannesw at openjdk.org  Mon Mar 10 07:57:05 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Mar 2025 07:57:05 GMT
Subject: Integrated: 8344301: Refine stylesheet for API docs
In-Reply-To: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
References: <q9-CN3bQcPn2eMPrRkVI9qT7zVCKNJUkbN-Exx8v3Kc=.a0e6aff2-5cf5-4ef1-a1ef-e9e8c8eb1c22@github.com>
Message-ID: <5vQClF-hTNQGGPtRJle8YtRR0BY1rkR7ogo6R2EOeAY=.2760f83f-84ac-4155-b007-1575c4cfd9aa@github.com>

On Tue, 18 Feb 2025 14:02:55 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.
> 
> List of changes:
> 
>  - Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged). 
>  - Fix font size and line height inconsistencies in many places.
>  - Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
>  - Remove light gray section background in class and module pages to simplify and unclutter the layout. 
>  - Add a subtle gray background to code elements in normal text to set them apart.
>  - Highlight headings of member details when they are used as link targets.
>  - Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
>  - Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
>  - Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
>  - Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
>  - Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
>  - Improve styling of additional HTML files in `doc-files` directories.
>  - Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
>  - Add background to `<pre>` elements (will look great with [JDK-8346118](https://bugs.openjdk.org/browse/JDK-8346118)).
>  - Various cleanup.
> 
> There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.
> 
> [Full JDK API docs are available for testing and comparison](https://cr.openjdk.org/~hannesw/8344301/api.05/index.html).

This pull request has now been integrated.

Changeset: 08872623
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/088726238664985ebf2bc60deca96f22245e9ce3
Stats:     425 lines in 7 files changed: 163 ins; 147 del; 115 mod

8344301: Refine stylesheet for API docs

Reviewed-by: liach, nbenalla

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

PR: https://git.openjdk.org/jdk/pull/23678

From hannesw at openjdk.org  Mon Mar 10 08:40:48 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Mar 2025 08:40:48 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v10]
In-Reply-To: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
Message-ID: <RxO6ol1RtqhR-shlu5hUvByXfDkP7gzy9WOfoywLn4A=.999291cb-22c1-4dd3-a31e-67d048feaaaf@github.com>

> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
> 
>  - <kbd>/</kbd> to switch focus to the search input
>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
> 
> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
> 
> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
> 
> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
> 
> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
> 
> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.

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 10 commits:

 - Merge branch 'master' into JDK-8350638
 - Wording
 - Reverse down/up arrows
 - Improve keyboard navigation help section
 - Add @bug id to tests
 - better workaround for focus-visible problem on Safari
   
   (Works in Safari Tech Preview, will work in release soon)
 - Use focus instead of focus-visible to always show focus
 - - Use themed focus highlight for TOC entries
   - Move focus back on input when typing on TOC focus
 - Move buttons to hide/show sidebar to the bottom and make them keyboard-accessible
 - 8350638: Make keyboard navigation more usable in API docs

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

Changes: https://git.openjdk.org/jdk/pull/23777/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23777&range=09
  Stats: 372 lines in 21 files changed: 229 ins; 52 del; 91 mod
  Patch: https://git.openjdk.org/jdk/pull/23777.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23777/head:pull/23777

PR: https://git.openjdk.org/jdk/pull/23777

From nbenalla at openjdk.org  Mon Mar 10 12:58:17 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 10 Mar 2025 12:58:17 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v5]
In-Reply-To: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
References: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
Message-ID: <x4u41-qCyk4PDa8EFGP4uWrUqSCayUYvEzjMUoI83c8=.ebf153c9-c6c5-4ddb-a8f6-83324d928623@github.com>

> This patch adds a new message when you run the `javadoc` executable with any arguments.
> Currently, unlike most other tools, running `javadoc` without any arguments does not show you how to use the tool or point you to use the `--help` option, this can be improved.
> 
> Before change:
> 
> W $ ./javadoc
> error: No modules, packages or classes specified.
> 1 error
> 
> 
> After change:
> 
> W $ ./javadoc
> Usage:
>     javadoc [options] [packagenames] [sourcefiles] [@files]
> For additional help on usage:           javadoc --help

Nizar Benalla 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 eight additional commits since the last revision:

 - review feedback: improve error message
 - Merge branch 'master' into javadoc-usage-message
 - update test
 - keep the same return value and write to STDERR
 - respond to feedback
 - Merge branch 'master' into javadoc-usage-message
 - update test with new usage message
 - improve javadoc executable message

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23618/files
  - new: https://git.openjdk.org/jdk/pull/23618/files/d67e033b..1814c4b0

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23618&range=04
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23618&range=03-04

  Stats: 39103 lines in 1148 files changed: 17535 ins; 15983 del; 5585 mod
  Patch: https://git.openjdk.org/jdk/pull/23618.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23618/head:pull/23618

PR: https://git.openjdk.org/jdk/pull/23618

From nbenalla at openjdk.org  Mon Mar 10 13:02:02 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 10 Mar 2025 13:02:02 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v5]
In-Reply-To: <x4u41-qCyk4PDa8EFGP4uWrUqSCayUYvEzjMUoI83c8=.ebf153c9-c6c5-4ddb-a8f6-83324d928623@github.com>
References: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
 <x4u41-qCyk4PDa8EFGP4uWrUqSCayUYvEzjMUoI83c8=.ebf153c9-c6c5-4ddb-a8f6-83324d928623@github.com>
Message-ID: <cNsOlaVvcnOgNihlgp6_M9qd6gOtLeuKnjupAbWk_Ec=.cd82ff86-3993-4529-95d5-2e15cbc8fee9@github.com>

On Mon, 10 Mar 2025 12:58:17 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> This patch adds a new message when you run the `javadoc` executable with any arguments.
>> Currently, unlike most other tools, running `javadoc` without any arguments does not show you how to use the tool or point you to use the `--help` option, this can be improved.
>> 
>> Before change:
>> 
>> W $ ./javadoc
>> error: No modules, packages or classes specified.
>> 1 error
>> 
>> 
>> After change:
>> 
>> W $ ./javadoc
>> Usage:
>>     javadoc [options] [packagenames] [sourcefiles] [@files]
>> For additional help on usage:           javadoc --help
>
> Nizar Benalla 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 eight additional commits since the last revision:
> 
>  - review feedback: improve error message
>  - Merge branch 'master' into javadoc-usage-message
>  - update test
>  - keep the same return value and write to STDERR
>  - respond to feedback
>  - Merge branch 'master' into javadoc-usage-message
>  - update test with new usage message
>  - improve javadoc executable message

nizar-mac! $ javadoc
Usage:
    javadoc [options] [packagenames] [sourcefiles] [@files]
For more details on available options, use --help or --help-extra
error: No modules, packages or classes specified.
1 error

flushing is necessary to print out the usage message consistently before the error

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

PR Comment: https://git.openjdk.org/jdk/pull/23618#issuecomment-2710516531

From liach at openjdk.org  Mon Mar 10 13:27:02 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 10 Mar 2025 13:27:02 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v10]
In-Reply-To: <RxO6ol1RtqhR-shlu5hUvByXfDkP7gzy9WOfoywLn4A=.999291cb-22c1-4dd3-a31e-67d048feaaaf@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
 <RxO6ol1RtqhR-shlu5hUvByXfDkP7gzy9WOfoywLn4A=.999291cb-22c1-4dd3-a31e-67d048feaaaf@github.com>
Message-ID: <qdThVMfdy5RVoPnmUE8acmxDiW5zMJzXUtsGtlFwq3M=.f0406558-7f35-4ee5-a3e6-24b48175d2ff@github.com>

On Mon, 10 Mar 2025 08:40:48 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
>> 
>>  - <kbd>/</kbd> to switch focus to the search input
>>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
>> 
>> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
>> 
>> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
>> 
>> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
>> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
>> 
>> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
>> 
>> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.
>
> 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 10 commits:
> 
>  - Merge branch 'master' into JDK-8350638
>  - Wording
>  - Reverse down/up arrows
>  - Improve keyboard navigation help section
>  - Add @bug id to tests
>  - better workaround for focus-visible problem on Safari
>    
>    (Works in Safari Tech Preview, will work in release soon)
>  - Use focus instead of focus-visible to always show focus
>  - - Use themed focus highlight for TOC entries
>    - Move focus back on input when typing on TOC focus
>  - Move buttons to hide/show sidebar to the bottom and make them keyboard-accessible
>  - 8350638: Make keyboard navigation more usable in API docs

Marked as reviewed by liach (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/23777#pullrequestreview-2670945495

From hannesw at openjdk.org  Mon Mar 10 13:32:01 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Mar 2025 13:32:01 GMT
Subject: Integrated: 8350638: Make keyboard navigation more usable in API docs
In-Reply-To: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
References: <Cz7JXcLsqFAALXCt1M-4NjIesL3g1FGC8u14wrXjHqM=.e4fad75d-0424-49ac-a3f7-abc4797c7fa5@github.com>
Message-ID: <4yVvkird-YRiVCM2-bFa673bqiSBqpYlqbhdUc_DV70=.16717cfb-5e55-40aa-8c0d-4dc685dd1c90@github.com>

On Tue, 25 Feb 2025 15:09:35 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to improve keyboard navigation in API documentation. Since the search feature was introduce in JDK 9 the search field grabbed the focus on page load, which is handy for searching but renders every other way of keyboard navigation impossible. With this change, instead of setting the focus on the search box, we introduce a few keyboard shortcuts to control focus:
> 
>  - <kbd>/</kbd> to switch focus to the search input
>  - <kbd>.</kbd> to switch focus to the sidebar filter input
>  - <kbd>Esc</kbd> to first reset input and then relinquish focus in either input field
> 
> Keyboard use of the TOC sidebar has also be greatly improved, it can now be navigated with the up/down arrow keys and lives up to the job of navigating to any page section very quickly. (I had a type-to-search version that was even quicker, but that's not allowed for accessibility unless there's a way to disable it.)
> 
> The feature [can be tested here][1]. There's also a [new section][2] on the Help page to document it.
> 
> [1]: https://cr.openjdk.org/~hannesw/8350638/api.00/java.base/java/lang/String.html 
> [2]: https://cr.openjdk.org/~hannesw/8350638/api.00/help-doc.html#help-keyboard-navigation
> 
> The Java changes in this PR are mostly to remove some elements from the tab order to be able to directly tab from the filter input to the results in the sidebar, and to add or improve messages for the feature itself or the new help section. 
> 
> The JavaScript changes may look a bit scary, but mostly I just added the keyboard listening code. The sidebar filtering code was just slightly improved and moved out into a separate component. Generally the script file looks a bit nicer now and hasn't grown all that much. The stylesheet changes are mostly to improve layout of the sidebar filter input and fix rendering bugs with the keyboard focus. Finally, I added a new `HtmlTree` factory method for `<kbd>` elements which I use in the help section as well as in the help box on the searchpage.

This pull request has now been integrated.

Changeset: e90b6bdb
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/e90b6bdb875315de6b962e2c7d36606d9a593eb9
Stats:     372 lines in 21 files changed: 229 ins; 52 del; 91 mod

8350638: Make keyboard navigation more usable in API docs

Reviewed-by: liach, nbenalla

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

PR: https://git.openjdk.org/jdk/pull/23777

From hannesw at openjdk.org  Mon Mar 10 15:46:52 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Mar 2025 15:46:52 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
Message-ID: <dX1QjYZMvLqrR9bS1YLuvpWlXWTcCo56grLUDgh59Pg=.f908cdb2-911a-4ca3-b86e-a07d86a92a6e@github.com>

Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.

[apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html

https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79

I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).

The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.

The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.

I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.

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

Commit messages:
 - Add svg files
 - 8350920: Allow inherited member summaries to be viewed inline

Changes: https://git.openjdk.org/jdk/pull/23967/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23967&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8350920
  Stats: 545 lines in 29 files changed: 430 ins; 55 del; 60 mod
  Patch: https://git.openjdk.org/jdk/pull/23967.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23967/head:pull/23967

PR: https://git.openjdk.org/jdk/pull/23967

From hannesw at openjdk.org  Mon Mar 10 15:57:02 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Mar 2025 15:57:02 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v5]
In-Reply-To: <x4u41-qCyk4PDa8EFGP4uWrUqSCayUYvEzjMUoI83c8=.ebf153c9-c6c5-4ddb-a8f6-83324d928623@github.com>
References: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
 <x4u41-qCyk4PDa8EFGP4uWrUqSCayUYvEzjMUoI83c8=.ebf153c9-c6c5-4ddb-a8f6-83324d928623@github.com>
Message-ID: <68udoUXFr-Y1eYrZTyyQJWWBkX4X29qrACYWEud3Uqg=.1e5fcb20-42ab-46ed-859d-1c9ac8d230d7@github.com>

On Mon, 10 Mar 2025 12:58:17 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> This patch adds a new message when you run the `javadoc` executable with any arguments.
>> Currently, unlike most other tools, running `javadoc` without any arguments does not show you how to use the tool or point you to use the `--help` option, this can be improved.
>> 
>> Before change:
>> 
>> W $ ./javadoc
>> error: No modules, packages or classes specified.
>> 1 error
>> 
>> 
>> After change:
>> 
>> W $ ./javadoc
>> Usage:
>>     javadoc [options] [packagenames] [sourcefiles] [@files]
>> For additional help on usage:           javadoc --help
>
> Nizar Benalla 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 eight additional commits since the last revision:
> 
>  - review feedback: improve error message
>  - Merge branch 'master' into javadoc-usage-message
>  - update test
>  - keep the same return value and write to STDERR
>  - respond to feedback
>  - Merge branch 'master' into javadoc-usage-message
>  - update test with new usage message
>  - improve javadoc executable message

Nice!

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23618#pullrequestreview-2671482448

From nbenalla at openjdk.org  Mon Mar 10 16:18:59 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 10 Mar 2025 16:18:59 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v5]
In-Reply-To: <x4u41-qCyk4PDa8EFGP4uWrUqSCayUYvEzjMUoI83c8=.ebf153c9-c6c5-4ddb-a8f6-83324d928623@github.com>
References: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
 <x4u41-qCyk4PDa8EFGP4uWrUqSCayUYvEzjMUoI83c8=.ebf153c9-c6c5-4ddb-a8f6-83324d928623@github.com>
Message-ID: <mPGb6yGRmtbKZUsjaUvcBN-P2awqNGTQFsptF1Lx5iw=.96fba8c3-d0a5-4ae3-afcd-a753d4c92466@github.com>

On Mon, 10 Mar 2025 12:58:17 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> This patch adds a new message when you run the `javadoc` executable with any arguments.
>> Currently, unlike most other tools, running `javadoc` without any arguments does not show you how to use the tool or point you to use the `--help` option, this can be improved.
>> 
>> Before change:
>> 
>> W $ ./javadoc
>> error: No modules, packages or classes specified.
>> 1 error
>> 
>> 
>> After change:
>> 
>> W $ ./javadoc
>> Usage:
>>     javadoc [options] [packagenames] [sourcefiles] [@files]
>> For additional help on usage:           javadoc --help
>
> Nizar Benalla 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 eight additional commits since the last revision:
> 
>  - review feedback: improve error message
>  - Merge branch 'master' into javadoc-usage-message
>  - update test
>  - keep the same return value and write to STDERR
>  - respond to feedback
>  - Merge branch 'master' into javadoc-usage-message
>  - update test with new usage message
>  - improve javadoc executable message

Thanks!

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

PR Comment: https://git.openjdk.org/jdk/pull/23618#issuecomment-2711122330

From nbenalla at openjdk.org  Mon Mar 10 16:18:59 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 10 Mar 2025 16:18:59 GMT
Subject: Integrated: 8350007: Add usage message to the javadoc executable
In-Reply-To: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
References: <dV9fCg-17wNUsIr6T02OwoIHg1vFAjZINje5CYhT6hY=.2198af40-1da1-48aa-ae43-b9cb26f25d60@github.com>
Message-ID: <JanELLbfcPrLhfv7W10fiG1mZy8p_PaTd0lDSMoIGHs=.a84a6d42-7810-4bbf-a769-7a8ea157e183@github.com>

On Thu, 13 Feb 2025 16:41:54 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> This patch adds a new message when you run the `javadoc` executable with any arguments.
> Currently, unlike most other tools, running `javadoc` without any arguments does not show you how to use the tool or point you to use the `--help` option, this can be improved.
> 
> Before change:
> 
> W $ ./javadoc
> error: No modules, packages or classes specified.
> 1 error
> 
> 
> After change:
> 
> W $ ./javadoc
> Usage:
>     javadoc [options] [packagenames] [sourcefiles] [@files]
> For additional help on usage:           javadoc --help

This pull request has now been integrated.

Changeset: 6b84bdef
Author:    Nizar Benalla <nbenalla at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/6b84bdef3b203e62cebd77705ef5b3e081302c28
Stats:     11 lines in 3 files changed: 6 ins; 1 del; 4 mod

8350007: Add usage message to the javadoc executable

Reviewed-by: hannesw

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

PR: https://git.openjdk.org/jdk/pull/23618

From hannesw at openjdk.org  Mon Mar 10 17:04:08 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Mar 2025 17:04:08 GMT
Subject: RFR: 8351555: Help section added in JDK-8350638 uses invalid HTML
Message-ID: <_Tzpwb1pijxgmeNToDh0psmfs-e-ZmF2UXEX3Nlim9o=.8f4277da-09f0-4e03-abb8-44c98ccb3f37@github.com>

Please review a change to fix the HTML for the new Keyboard Navigation section added in [JDK-8350638](https://bugs.openjdk.org/browse/JDK-8350638). Instead of adding the `<ul>` element to the `<p>` element, both elements are added to the `<section>` element.

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

Commit messages:
 - 8351555: Help section added in JDK-8350638 uses invalid HTML

Changes: https://git.openjdk.org/jdk/pull/23969/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23969&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8351555
  Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/23969.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23969/head:pull/23969

PR: https://git.openjdk.org/jdk/pull/23969

From liach at openjdk.org  Mon Mar 10 17:25:01 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 10 Mar 2025 17:25:01 GMT
Subject: RFR: 8351555: Help section added in JDK-8350638 uses invalid HTML
In-Reply-To: <_Tzpwb1pijxgmeNToDh0psmfs-e-ZmF2UXEX3Nlim9o=.8f4277da-09f0-4e03-abb8-44c98ccb3f37@github.com>
References: <_Tzpwb1pijxgmeNToDh0psmfs-e-ZmF2UXEX3Nlim9o=.8f4277da-09f0-4e03-abb8-44c98ccb3f37@github.com>
Message-ID: <gdj9xqoYgQ6IMMu-wdMZFSybixOpvCvctkn9pyfcOxY=.fd6324e1-bfb1-4a97-9b3a-8461fef50506@github.com>

On Mon, 10 Mar 2025 16:59:17 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to fix the HTML for the new Keyboard Navigation section added in [JDK-8350638](https://bugs.openjdk.org/browse/JDK-8350638). Instead of adding the `<ul>` element to the `<p>` element, both elements are added to the `<section>` element.

Marked as reviewed by liach (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/23969#pullrequestreview-2671706999

From jjg at openjdk.org  Mon Mar 10 17:25:01 2025
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 10 Mar 2025 17:25:01 GMT
Subject: RFR: 8351555: Help section added in JDK-8350638 uses invalid HTML
In-Reply-To: <_Tzpwb1pijxgmeNToDh0psmfs-e-ZmF2UXEX3Nlim9o=.8f4277da-09f0-4e03-abb8-44c98ccb3f37@github.com>
References: <_Tzpwb1pijxgmeNToDh0psmfs-e-ZmF2UXEX3Nlim9o=.8f4277da-09f0-4e03-abb8-44c98ccb3f37@github.com>
Message-ID: <FN9Xc3x1Yu6ZMIWu0UQfaAgvFRT5fwZ2043jJyyVevg=.cef3590f-685c-4f72-86d2-63718fa4619e@github.com>

On Mon, 10 Mar 2025 16:59:17 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to fix the HTML for the new Keyboard Navigation section added in [JDK-8350638](https://bugs.openjdk.org/browse/JDK-8350638). Instead of adding the `<ul>` element to the `<p>` element, both elements are added to the `<section>` element.

As well as `noreg-trivial, I would suggest `noreg-other`, since the output is not dependent on user input and should be caught by `tidy`

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

Marked as reviewed by jjg (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23969#pullrequestreview-2671711698

From hannesw at openjdk.org  Mon Mar 10 17:25:02 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 10 Mar 2025 17:25:02 GMT
Subject: Integrated: 8351555: Help section added in JDK-8350638 uses invalid
 HTML
In-Reply-To: <_Tzpwb1pijxgmeNToDh0psmfs-e-ZmF2UXEX3Nlim9o=.8f4277da-09f0-4e03-abb8-44c98ccb3f37@github.com>
References: <_Tzpwb1pijxgmeNToDh0psmfs-e-ZmF2UXEX3Nlim9o=.8f4277da-09f0-4e03-abb8-44c98ccb3f37@github.com>
Message-ID: <KX_nBoC99ZmENUFoKrMf4DKEADuUatpgH1YMV0Yp5Ho=.d3583b7c-a41c-407d-87b2-cdb6269ede56@github.com>

On Mon, 10 Mar 2025 16:59:17 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to fix the HTML for the new Keyboard Navigation section added in [JDK-8350638](https://bugs.openjdk.org/browse/JDK-8350638). Instead of adding the `<ul>` element to the `<p>` element, both elements are added to the `<section>` element.

This pull request has now been integrated.

Changeset: 7999091e
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/7999091e3e976fe62d859d508bf649b6ec7bc94e
Stats:     2 lines in 1 file changed: 0 ins; 0 del; 2 mod

8351555: Help section added in JDK-8350638 uses invalid HTML

Reviewed-by: liach, jjg

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

PR: https://git.openjdk.org/jdk/pull/23969

From hannesw at openjdk.org  Tue Mar 11 14:37:36 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 11 Mar 2025 14:37:36 GMT
Subject: RFR: 8345555: Improve layout of search results [v4]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <TN8l8lW4cCM8Jotia0HZehXacoEuW5YsdYjA9wyC27E=.47194b24-565d-42a3-8e18-d36d6553cf11@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.02/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

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:

 - Make standalone search page keyboard-friendly
 - Merge branch 'master' into javadoc-search
 - Review feedback (formatting)
 - Remove counterproductive restriction in search pattern
 - Fix search menu selecting item at current mouse position
 - Rename label property as it has special meaning to jquery-ui
 - 8345555: Improve layout of search results

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

Changes: https://git.openjdk.org/jdk/pull/23666/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=03
  Stats: 799 lines in 26 files changed: 418 ins; 84 del; 297 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From hannesw at openjdk.org  Tue Mar 11 17:42:36 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 11 Mar 2025 17:42:36 GMT
Subject: RFR: 8345555: Improve layout of search results [v5]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <UrjW9GuuQLMBmu4W4hCM_zjSwpgoOeTDtrdwZN8Stvo=.00050785-3c8f-49f8-a709-ad2c68f09c77@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Improve focus handling

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/ea0a1834..478c22d1

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=04
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=03-04

  Stats: 36 lines in 2 files changed: 15 ins; 6 del; 15 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From nbenalla at openjdk.org  Tue Mar 11 18:01:03 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 11 Mar 2025 18:01:03 GMT
Subject: RFR: 8345555: Improve layout of search results [v5]
In-Reply-To: <UrjW9GuuQLMBmu4W4hCM_zjSwpgoOeTDtrdwZN8Stvo=.00050785-3c8f-49f8-a709-ad2c68f09c77@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <UrjW9GuuQLMBmu4W4hCM_zjSwpgoOeTDtrdwZN8Stvo=.00050785-3c8f-49f8-a709-ad2c68f09c77@github.com>
Message-ID: <G6GNrW74gna6rPX_ifmzLbkXRSECBOCZavX_u8hv4ZA=.7cb7aeab-9dba-48b2-9b0e-b1c8e331017a@github.com>

On Tue, 11 Mar 2025 17:42:36 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
>> 
>> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>> 
>> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>> 
>> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>> 
>> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
>> 
>> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>> 
>> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to ...
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Improve focus handling

Sorry, I lost track of this PR. Currently reviewing.

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

PR Comment: https://git.openjdk.org/jdk/pull/23666#issuecomment-2715235089

From hannesw at openjdk.org  Wed Mar 12 10:47:21 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 10:47:21 GMT
Subject: RFR: 8345555: Improve layout of search results [v6]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <bXlTSN1sGtg1jPwYQh8tMBjUiOEz3c42juAQjdETPcA=.8fb204ee-7b20-4387-b85b-eb5d7e7530a8@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Implement module selector for search page

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/478c22d1..008c331d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=05
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=04-05

  Stats: 271 lines in 15 files changed: 138 ins; 68 del; 65 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From hannesw at openjdk.org  Wed Mar 12 10:53:42 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 10:53:42 GMT
Subject: RFR: 8345555: Improve layout of search results [v7]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <BmCa2JxEaVWtWMEqEMsRJAN7b2bbLTsi-g6rkigRmgI=.fc2a9a97-3589-414d-8b86-e3d7f546763e@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Simplify lambda

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/008c331d..a2793957

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=06
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=05-06

  Stats: 5 lines in 1 file changed: 0 ins; 4 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From hannesw at openjdk.org  Wed Mar 12 11:12:41 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 11:12:41 GMT
Subject: RFR: 8345555: Improve layout of search results [v8]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <5axi5JeLlDSlkGnYyn-A52aBf1dMxzuUZvcXUCl2pKc=.8a93af9b-7fbc-4272-9a6f-b22ee44555b5@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Add back tab switch from packages to types

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/a2793957..1691d4f1

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=07
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=06-07

  Stats: 6 lines in 1 file changed: 2 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From hannesw at openjdk.org  Wed Mar 12 13:27:36 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 13:27:36 GMT
Subject: RFR: 8351626: Update remaining icons to SVG format
Message-ID: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>

Please review a change to update the remaining `.png` files used by JavaDoc with `.svg` files. In addition to the looking glass and "x" icons used in the search box this also adds left and right pointing angles used in breadcrumb navigation and sidebar hide/show buttons that previously used glyphs.

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

Commit messages:
 - 8351626: Update remaining icons to SVG format

Changes: https://git.openjdk.org/jdk/pull/24007/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24007&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8351626
  Stats: 104 lines in 17 files changed: 72 ins; 4 del; 28 mod
  Patch: https://git.openjdk.org/jdk/pull/24007.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24007/head:pull/24007

PR: https://git.openjdk.org/jdk/pull/24007

From nbenalla at openjdk.org  Wed Mar 12 14:10:01 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 12 Mar 2025 14:10:01 GMT
Subject: RFR: 8351626: Update remaining icons to SVG format
In-Reply-To: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
References: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
Message-ID: <iuuZONXpHoyNiZqb1i74x928XNxGM2aHMo7pLqnrrDw=.1b8be812-9dd2-43eb-aa11-bf6a5ab0584c@github.com>

On Wed, 12 Mar 2025 13:22:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update the remaining `.png` files used by JavaDoc with `.svg` files. In addition to the looking glass and "x" icons used in the search box this also adds left and right pointing angles used in breadcrumb navigation and sidebar hide/show buttons that previously used glyphs.

Looks good and trivial.

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/24007#pullrequestreview-2678652211

From jjg at openjdk.org  Wed Mar 12 15:19:52 2025
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 12 Mar 2025 15:19:52 GMT
Subject: RFR: 8351626: Update remaining icons to SVG format
In-Reply-To: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
References: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
Message-ID: <xC5a_xb-44P9B_8bRFuM-0JV3yd-JTl3zIAfUY4rSxM=.2d354557-6cc0-4cbe-803c-050a9509c335@github.com>

On Wed, 12 Mar 2025 13:22:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update the remaining `.png` files used by JavaDoc with `.svg` files. In addition to the looking glass and "x" icons used in the search box this also adds left and right pointing angles used in breadcrumb navigation and sidebar hide/show buttons that previously used glyphs.

Marked as reviewed by jjg (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/24007#pullrequestreview-2678910178

From hannesw at openjdk.org  Wed Mar 12 15:56:58 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 15:56:58 GMT
Subject: RFR: 8351626: Update remaining icons to SVG format
In-Reply-To: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
References: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
Message-ID: <7xG8BIWlaF6JBP1TupP6G-Ra15wsS39PJU0gPMW1n1Y=.50134722-787e-46b4-89bf-27aa12a670e6@github.com>

On Wed, 12 Mar 2025 13:22:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update the remaining `.png` files used by JavaDoc with `.svg` files. In addition to the looking glass and "x" icons used in the search box this also adds left and right pointing angles used in breadcrumb navigation and sidebar hide/show buttons that previously used glyphs.

Thanks!

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

PR Comment: https://git.openjdk.org/jdk/pull/24007#issuecomment-2718350124

From hannesw at openjdk.org  Wed Mar 12 15:56:59 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 15:56:59 GMT
Subject: Integrated: 8351626: Update remaining icons to SVG format
In-Reply-To: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
References: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
Message-ID: <ac1h3iEhtKKsBmkK7qaTD7n3EjAUNyu1hqWfUVIGzuM=.0238bcb3-b691-4a81-8760-7d55c0f42a37@github.com>

On Wed, 12 Mar 2025 13:22:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update the remaining `.png` files used by JavaDoc with `.svg` files. In addition to the looking glass and "x" icons used in the search box this also adds left and right pointing angles used in breadcrumb navigation and sidebar hide/show buttons that previously used glyphs.

This pull request has now been integrated.

Changeset: f16a7426
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/f16a74260f329ccef51faa2e375bce5947057a49
Stats:     104 lines in 17 files changed: 72 ins; 4 del; 28 mod

8351626: Update remaining icons to SVG format

Reviewed-by: nbenalla, jjg

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

PR: https://git.openjdk.org/jdk/pull/24007

From hannesw at openjdk.org  Wed Mar 12 16:25:42 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 16:25:42 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v2]
In-Reply-To: <dX1QjYZMvLqrR9bS1YLuvpWlXWTcCo56grLUDgh59Pg=.f908cdb2-911a-4ca3-b86e-a07d86a92a6e@github.com>
References: <dX1QjYZMvLqrR9bS1YLuvpWlXWTcCo56grLUDgh59Pg=.f908cdb2-911a-4ca3-b86e-a07d86a92a6e@github.com>
Message-ID: <RgmwHD6t4dj1q6gSOcn37xIaxP7FIceOxBHdqcI8cCo=.3fabacf1-3b3a-470e-9e41-af1b23017abc@github.com>

> Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.
> 
> [apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html
> 
> https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79
> 
> I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).
> 
> The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.
> 
> The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.
> 
> I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.

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 three commits:

 - Merge branch 'master' into JDK-8350920
 - Add svg files
 - 8350920: Allow inherited member summaries to be viewed inline

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

Changes: https://git.openjdk.org/jdk/pull/23967/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23967&range=01
  Stats: 524 lines in 27 files changed: 411 ins; 55 del; 58 mod
  Patch: https://git.openjdk.org/jdk/pull/23967.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23967/head:pull/23967

PR: https://git.openjdk.org/jdk/pull/23967

From nbenalla at openjdk.org  Wed Mar 12 17:07:59 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 12 Mar 2025 17:07:59 GMT
Subject: RFR: 8351626: Update remaining icons to SVG format
In-Reply-To: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
References: <S4fUIiyGsfqOOdpn4wocGGrFhzDvJA0igYYhKumPPQE=.6f27913a-0b25-4771-8368-9bca6ced4ce8@github.com>
Message-ID: <ZtI4qRElB51Ivy1cKjvtC6068PWcLQG9ww_yGRrC9Co=.13fba13f-8970-429c-9709-297d6eeec9da@github.com>

On Wed, 12 Mar 2025 13:22:07 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a change to update the remaining `.png` files used by JavaDoc with `.svg` files. In addition to the looking glass and "x" icons used in the search box this also adds left and right pointing angles used in breadcrumb navigation and sidebar hide/show buttons that previously used glyphs.

Apologies, I missed this while reviewing but it seems like `tidy` is complaining about the lack of the `alt` property.

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

PR Comment: https://git.openjdk.org/jdk/pull/24007#issuecomment-2718553958

From nbenalla at openjdk.org  Wed Mar 12 18:13:21 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 12 Mar 2025 18:13:21 GMT
Subject: RFR: 8351881: Tidy complains about missing "alt" attribute
Message-ID: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>

Please review this change to add missing "alt" attributes to the left and right pointing angles used in the sidebar hide/show buttons and prevent `jdkCheckHtml.java` from failing.

TIA.

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

Commit messages:
 - add missing alt attribute

Changes: https://git.openjdk.org/jdk/pull/24016/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24016&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8351881
  Stats: 4 lines in 1 file changed: 2 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/24016.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24016/head:pull/24016

PR: https://git.openjdk.org/jdk/pull/24016

From hannesw at openjdk.org  Wed Mar 12 18:29:52 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 12 Mar 2025 18:29:52 GMT
Subject: RFR: 8351881: Tidy complains about missing "alt" attribute
In-Reply-To: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
References: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
Message-ID: <9en-7Q6zwGnJuZ5GxLEMFoRTKIpHc63LshrlftM2I0Y=.397a1a18-f06a-40d0-9eaf-80fbaf5ae84c@github.com>

On Wed, 12 Mar 2025 18:08:24 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this change to add missing "alt" attributes to the left and right pointing angles used in the sidebar hide/show buttons and prevent `jdkCheckHtml.java` from failing.
> 
> TIA.

Looks good, thanks for fixing.

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24016#pullrequestreview-2679506704

From jjg at openjdk.org  Wed Mar 12 18:46:57 2025
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 12 Mar 2025 18:46:57 GMT
Subject: RFR: 8351881: Tidy complains about missing "alt" attribute
In-Reply-To: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
References: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
Message-ID: <nRr_Xm-8lM2ZIR5o93EOD8vVXQOEmRHMEhNi_0virqs=.467a0936-8eb2-47c6-bf91-c4f0ba49cf11@github.com>

On Wed, 12 Mar 2025 18:08:24 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this change to add missing "alt" attributes to the left and right pointing angles used in the sidebar hide/show buttons and prevent `jdkCheckHtml.java` from failing.
> 
> TIA.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TableOfContents.java line 114:

> 112:                         .put(HtmlAttr.SRC, writer.pathToRoot.resolve(DocPaths.RESOURCE_FILES)
> 113:                                 .resolve(DocPaths.LEFT_SVG).getPath())
> 114:                         .put(HtmlAttr.ALT, writer.contents.hideSidebar.toString())));

It would be better to introduce and use a new factory method in HtmlTree

    HtmlTree IMG(DocPath src, String alt)

so that the API makes any similar error less likely in future.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24016#discussion_r1992103888

From nbenalla at openjdk.org  Wed Mar 12 18:53:53 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 12 Mar 2025 18:53:53 GMT
Subject: RFR: 8351881: Tidy complains about missing "alt" attribute
In-Reply-To: <nRr_Xm-8lM2ZIR5o93EOD8vVXQOEmRHMEhNi_0virqs=.467a0936-8eb2-47c6-bf91-c4f0ba49cf11@github.com>
References: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
 <nRr_Xm-8lM2ZIR5o93EOD8vVXQOEmRHMEhNi_0virqs=.467a0936-8eb2-47c6-bf91-c4f0ba49cf11@github.com>
Message-ID: <A8lc3KYEPqRZ8fVFdEcGkdM5rAhMiw4u9t4RvBSwzTM=.6c41f364-84a7-42e9-b53d-b94f418c42a1@github.com>

On Wed, 12 Mar 2025 18:44:09 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review this change to add missing "alt" attributes to the left and right pointing angles used in the sidebar hide/show buttons and prevent `jdkCheckHtml.java` from failing.
>> 
>> TIA.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TableOfContents.java line 114:
> 
>> 112:                         .put(HtmlAttr.SRC, writer.pathToRoot.resolve(DocPaths.RESOURCE_FILES)
>> 113:                                 .resolve(DocPaths.LEFT_SVG).getPath())
>> 114:                         .put(HtmlAttr.ALT, writer.contents.hideSidebar.toString())));
> 
> It would be better to introduce and use a new factory method in HtmlTree
> 
>     HtmlTree IMG(DocPath src, String alt)
> 
> so that the API makes any similar error less likely in future.

I will add this in a follow up PR, thanks for the suggestion

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24016#discussion_r1992113020

From nbenalla at openjdk.org  Wed Mar 12 18:59:57 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 12 Mar 2025 18:59:57 GMT
Subject: Integrated: 8351881: Tidy complains about missing "alt" attribute
In-Reply-To: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
References: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
Message-ID: <UDvPLo4mM07lL4Uqbh__bfkqZwXGPidk5ap5Yjt6Jwc=.c0db6e9a-d0af-472e-bf48-da3c7a8ba2a0@github.com>

On Wed, 12 Mar 2025 18:08:24 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this change to add missing "alt" attributes to the left and right pointing angles used in the sidebar hide/show buttons and prevent `jdkCheckHtml.java` from failing.
> 
> TIA.

This pull request has now been integrated.

Changeset: db531bf7
Author:    Nizar Benalla <nbenalla at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/db531bf7df517eb6a07080aceb2a88a3b90d5e94
Stats:     4 lines in 1 file changed: 2 ins; 0 del; 2 mod

8351881: Tidy complains about missing "alt" attribute

Reviewed-by: hannesw

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

PR: https://git.openjdk.org/jdk/pull/24016

From jjg at openjdk.org  Thu Mar 13 03:07:04 2025
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 13 Mar 2025 03:07:04 GMT
Subject: RFR: 8351881: Tidy complains about missing "alt" attribute
In-Reply-To: <A8lc3KYEPqRZ8fVFdEcGkdM5rAhMiw4u9t4RvBSwzTM=.6c41f364-84a7-42e9-b53d-b94f418c42a1@github.com>
References: <XBji13rIec9kIdULsQJcMvw0A-K-grQqWc6MFgFjXxg=.cf63a817-b0c9-4b78-9ca1-61dfa8df3842@github.com>
 <nRr_Xm-8lM2ZIR5o93EOD8vVXQOEmRHMEhNi_0virqs=.467a0936-8eb2-47c6-bf91-c4f0ba49cf11@github.com>
 <A8lc3KYEPqRZ8fVFdEcGkdM5rAhMiw4u9t4RvBSwzTM=.6c41f364-84a7-42e9-b53d-b94f418c42a1@github.com>
Message-ID: <Q961JiCZqMhHAPmpMw1GYxVLOkSvWTT5Lmx6wkaSPkY=.293a4e9d-1b17-44bf-a4fa-b87d24640f14@github.com>

On Wed, 12 Mar 2025 18:51:07 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TableOfContents.java line 114:
>> 
>>> 112:                         .put(HtmlAttr.SRC, writer.pathToRoot.resolve(DocPaths.RESOURCE_FILES)
>>> 113:                                 .resolve(DocPaths.LEFT_SVG).getPath())
>>> 114:                         .put(HtmlAttr.ALT, writer.contents.hideSidebar.toString())));
>> 
>> It would be better to introduce and use a new factory method in HtmlTree
>> 
>>     HtmlTree IMG(DocPath src, String alt)
>> 
>> so that the API makes any similar error less likely in future.
>
> I will add this in a follow up PR, thanks for the suggestion

Consider it a general principle, to use static factory methods in HtmlTree to establish preferred or convenient ways to reliably create valid tree nodes.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24016#discussion_r1992606647

From nbenalla at openjdk.org  Thu Mar 13 10:12:06 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Thu, 13 Mar 2025 10:12:06 GMT
Subject: RFR: 8345555: Improve layout of search results [v8]
In-Reply-To: <5axi5JeLlDSlkGnYyn-A52aBf1dMxzuUZvcXUCl2pKc=.8a93af9b-7fbc-4272-9a6f-b22ee44555b5@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <5axi5JeLlDSlkGnYyn-A52aBf1dMxzuUZvcXUCl2pKc=.8a93af9b-7fbc-4272-9a6f-b22ee44555b5@github.com>
Message-ID: <iE59AYK0xwMGN8a1UvgZCQz-kAhpdy4WjrKoYg3y37Q=.1ad3f86d-cf73-4b51-be16-88266fab0d93@github.com>

On Wed, 12 Mar 2025 11:12:41 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
>> 
>> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>> 
>> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>> 
>> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>> 
>> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
>> 
>> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>> 
>> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to ...
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add back tab switch from packages to types

I think the code is fine, I like the new search feature but I have some nits.

- I used an automated script to check the copyright headers. I believe these files need to have the copyright years updated 

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexWriter.java
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SpecTaglet.java
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SystemPropertyTaglet.java
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/TagletWriter.java
src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlAttr.java
src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTag.java
test/langtools/jdk/javadoc/doclet/testIndex/TestIndex.java
test/langtools/jdk/javadoc/doclet/testIndexInDocFiles/TestIndexInDocFiles.java
test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java
test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java
test/langtools/jdk/javadoc/doclet/testUnnamedPackage/TestUnnamedPackage.java


- Adding the bug id to the tests would be good too.

- Could we add more CSS to the select box (to filter modules) in the search page? It stands out a little.

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

PR Comment: https://git.openjdk.org/jdk/pull/23666#issuecomment-2720687925

From hannesw at openjdk.org  Thu Mar 13 18:19:03 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 13 Mar 2025 18:19:03 GMT
Subject: Withdrawn: 8346118: Improve whitespace normalization in preformatted
 text
In-Reply-To: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
Message-ID: <YikWRSACT4bffehINlc8u6-3j51IDIA0OAVNZze6qHQ=.749a79ed-dc49-4c50-84b5-f75005596c7e@github.com>

On Mon, 3 Mar 2025 16:41:18 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
> 
> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
> 
> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
> 
> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
> 
> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
> 
> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element

This pull request has been closed without being integrated.

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

PR: https://git.openjdk.org/jdk/pull/23868

From hannesw at openjdk.org  Thu Mar 13 18:19:02 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 13 Mar 2025 18:19:02 GMT
Subject: RFR: 8346118: Improve whitespace normalization in preformatted
 text
In-Reply-To: <ytiC5aoARrCzdFLE1X3jpB4mTEDRrZwcC2Vs6mNnZwo=.f8783235-5734-4fd0-8bc2-4f2b2da0e91b@github.com>
References: <ttHVSSUCm3Rgrc4902K8uC-WY9Jf0CmBXxP9DrNgUNs=.05ae2161-2a54-4019-b2a1-79e2c9352843@github.com>
 <ytiC5aoARrCzdFLE1X3jpB4mTEDRrZwcC2Vs6mNnZwo=.f8783235-5734-4fd0-8bc2-4f2b2da0e91b@github.com>
Message-ID: <qv65vfh6PcBFOgwCZWxAM11ojhfev2liz1PaxWZ660E=.9aee7b66-f244-4e96-bf4e-4b114c2aa617@github.com>

On Wed, 5 Mar 2025 18:07:11 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review an enhancement to make `DocCommentParser` normalize whitespace inside `<pre>` elements. The normalization is conceptually simple and and intended to be minimally invasive. Before parsing, `DocCommentParser` checks whether the text is a traditional doc comment and whether every line starts with a space character, which is commonly the case in traditional doc comments. If so, a single leading space is removed in block content (top level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>` tags.
>> 
>> This fixes the incidental one-space indentation in the vast majority of JDK code samples using `<pre>` alone or in combination with `<code>` or `{@code}`. In fact, I only found one code sample in JDK code that isn't solved by this change, for which I included a fix in this PR (it's in `String.startsWith(String, int)`, where I replaced the 10 char indentation and trailing line with a `<blockquote>`). 
>> 
>> The many added `boolean inBlockContent` arguments pased around in `DocCommentParser` are to make sure the removal is not applied to multiline inline content, which is maybe a bit fussy considering there is not a lot of multiline inline content in `<pre>` tags and it usually would not mind about removal of a non-essential space character, but I wanted to keep the change minimal. There are few javadoc tests that had to be adapted, most of the testing is done in `test/langtools/tools/javac/doctree`. 
>> 
>> If the exact number of leading whitespace in `<pre>` tags is important to any javadoc user the old output can be restored by increasing the indentation by 1. There will be a release note for this of course. 
>> 
>> Unfortunately, there is another whitespace problem that can't be solved as easily, and that is a leading blank line caused by `<pre><code>\n` open tags. Browsers will [ignore a newline immediately following a `<pre>` tag][1], but not if there is a `<code>` tag in between. There are hundreds of occurrences of this in JDK code, including variants with space characters mixed in. The fix in javadoc proper would be too complex, so I decided to solve it with 3 lines of JavaScript and a regex to reverse the order of `<code>\n` at the beginning of `<pre>` tags while removing any intermediary space. Script operation is indiscernible and it solves the problem.
>> 
>> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element
>
> As you indicated, there are two problems being addressed here, which might indicate the need for two separate patches. These issues are:
> 
> 1. The leading 1-space problem.
> 2. The trailing newline-after-<pre> problem
> 
> For the first, it is unduly hard work to fix this just for `<pre>` blocks. I still think that an overall better long-term solution would be to apply a conceptual `stripIndent` to the entire doc comment. This would bring traditional comments into line with the new Markdown comments, and can be done in just a few lines in `DocCommentParser`, and doing it there in DCP means you need not update `Elements.getDocComment`. If nothing else, I would suggest doing the experiment and comparing the generated docs, to verify there are no unexpected side effects. If there are any significant unexpected side effects, then your approach might deserve a second look. You could also make this a JDK-version-specific change if you wanted: meaning the new behavior does not apply to older JDK versions, although that is not a policy we have adhered to in the past.
> 
> For the second, I just feel that is a step too far, using JavaScript to clean up what some might consider to be bad input. Authors should either write HTML according to the HTML (and CSS?) specs, so that `javadoc` is just a "pass-through" layer, or authors should use a suitable construct, like `{@snippet...}`, that is "pleasing" to look at in source form while still generating the desired output.

After discussion with @jonathan-gibbons we have agreed that the two issues in this PR should be handled separately.

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

PR Comment: https://git.openjdk.org/jdk/pull/23868#issuecomment-2722311586

From hannesw at openjdk.org  Fri Mar 14 10:49:15 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 14 Mar 2025 10:49:15 GMT
Subject: RFR: 8345555: Improve layout of search results [v9]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <d8KON5aOIpu95virS6vBIiMEtutsfwlXd5IP9tTarFI=.e5a61197-a79e-4ac1-9668-1500897ef901@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Add styles for module selector

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/1691d4f1..2a2e04f1

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=08
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=07-08

  Stats: 7 lines in 1 file changed: 5 ins; 1 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From hannesw at openjdk.org  Fri Mar 14 13:46:09 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 14 Mar 2025 13:46:09 GMT
Subject: RFR: 8345555: Improve layout of search results [v10]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <krh_JOTlvyHQYIVpHg9d1MU5JVhg5ga43ixjrqDeUNE=.9fcca3c4-d92c-4157-9d42-fddfeba95726@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:

 - Add bug id to more tests
 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java due to 973bf1362eb
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexWriter.java due to 65de882c21a
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SpecTaglet.java due to 973bf1362eb
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SystemPropertyTaglet.java due to 973bf1362eb
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/TagletWriter.java due to 973bf1362eb
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlAttr.java due to 008c331d854
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTag.java due to 008c331d854
    + update test/langtools/jdk/javadoc/doclet/testIndex/TestIndex.java due to 973bf1362eb
    + update test/langtools/jdk/javadoc/doclet/testIndexInDocFiles/TestIndexInDocFiles.java due to 973bf1362eb
    + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 973bf1362eb
    + update test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java due to 973bf1362eb
    + update test/langtools/jdk/javadoc/doclet/testUnnamedPackage/TestUnnamedPackage.java due to 973bf1362eb

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/2a2e04f1..e95acda7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=09
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=08-09

  Stats: 16 lines in 14 files changed: 0 ins; 0 del; 16 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From nbenalla at openjdk.org  Fri Mar 14 14:03:59 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 14 Mar 2025 14:03:59 GMT
Subject: RFR: 8345555: Improve layout of search results [v10]
In-Reply-To: <krh_JOTlvyHQYIVpHg9d1MU5JVhg5ga43ixjrqDeUNE=.9fcca3c4-d92c-4157-9d42-fddfeba95726@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <krh_JOTlvyHQYIVpHg9d1MU5JVhg5ga43ixjrqDeUNE=.9fcca3c4-d92c-4157-9d42-fddfeba95726@github.com>
Message-ID: <Dsao6pJVBucstNE8TYMF3vmD6MyWmiehg6-0OcOIDzQ=.65f96c14-82f8-409d-a5de-d48ea83087c2@github.com>

On Fri, 14 Mar 2025 13:46:09 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
>> 
>> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>> 
>> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>> 
>> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>> 
>> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
>> 
>> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>> 
>> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to ...
>
> Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Add bug id to more tests
>  - Update copyright years
>    
>    Note: any commit hashes below might be outdated due to subsequent
>    history rewriting (e.g. git rebase).
>    
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java due to 973bf1362eb
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexWriter.java due to 65de882c21a
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SpecTaglet.java due to 973bf1362eb
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SystemPropertyTaglet.java due to 973bf1362eb
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/TagletWriter.java due to 973bf1362eb
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlAttr.java due to 008c331d854
>     + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTag.java due to 008c331d854
>     + update test/langtools/jdk/javadoc/doclet/testIndex/TestIndex.java due to 973bf1362eb
>     + update test/langtools/jdk/javadoc/doclet/testIndexInDocFiles/TestIndexInDocFiles.java due to 973bf1362eb
>     + update test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java due to 973bf1362eb
>     + update test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java due to 973bf1362eb
>     + update test/langtools/jdk/javadoc/doclet/testUnnamedPackage/TestUnnamedPackage.java due to 973bf1362eb

I've checked the new CSS on multiple browsers. Copyright years and bug ids have been updated.

Latest change looks good!

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/23666#pullrequestreview-2685664543

From hannesw at openjdk.org  Sat Mar 15 06:48:52 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Sat, 15 Mar 2025 06:48:52 GMT
Subject: RFR: 8345555: Improve layout of search results [v11]
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Fix maximum size for search menu
   - Correctly calculate available vertical space
   - Align width with page content with visible sidebar
   - Allow more width on small displays
   - Add padding to result text label

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23666/files
  - new: https://git.openjdk.org/jdk/pull/23666/files/e95acda7..cb3c51f8

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=10
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=23666&range=09-10

  Stats: 7 lines in 1 file changed: 2 ins; 0 del; 5 mod
  Patch: https://git.openjdk.org/jdk/pull/23666.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23666/head:pull/23666

PR: https://git.openjdk.org/jdk/pull/23666

From liach at openjdk.org  Sat Mar 15 15:48:57 2025
From: liach at openjdk.org (Chen Liang)
Date: Sat, 15 Mar 2025 15:48:57 GMT
Subject: RFR: 8345555: Improve layout of search results [v11]
In-Reply-To: <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>
Message-ID: <TbKERtZdD7OYMFWdYvZ0bcZMTMJboiotzv5p7UPkuLA=.3c7ed9ba-bf3a-49ce-ba05-927d0804c22b@github.com>

On Sat, 15 Mar 2025 06:48:52 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
>> 
>> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>> 
>> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>> 
>> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>> 
>> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
>> 
>> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>> 
>> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to ...
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix maximum size for search menu
>    - Correctly calculate available vertical space
>    - Align width with page content with visible sidebar
>    - Allow more width on small displays
>    - Add padding to result text label

test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java line 467:

> 465:         checkOutput("index-all.html", true,
> 466:                 """
> 467:                     <a href="pkg2/Foo.html#method(java.util.Vector)" class="member-name-link">method(Vector&lt;Object&gt;)</a>"""

Is this caused by replacing `Util.flatSignature` with `makeSignature(.., false, true)`?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23666#discussion_r1996980901

From hannesw at openjdk.org  Sat Mar 15 16:10:58 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Sat, 15 Mar 2025 16:10:58 GMT
Subject: RFR: 8345555: Improve layout of search results [v11]
In-Reply-To: <TbKERtZdD7OYMFWdYvZ0bcZMTMJboiotzv5p7UPkuLA=.3c7ed9ba-bf3a-49ce-ba05-927d0804c22b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>
 <TbKERtZdD7OYMFWdYvZ0bcZMTMJboiotzv5p7UPkuLA=.3c7ed9ba-bf3a-49ce-ba05-927d0804c22b@github.com>
Message-ID: <1POoukxSBT8fiGyhn53XWfFJ2QA57V5oT8OYhTu9UOE=.6d0e04d0-e42b-4e63-8b05-58690e03643e@github.com>

On Sat, 15 Mar 2025 15:45:48 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix maximum size for search menu
>>    - Correctly calculate available vertical space
>>    - Align width with page content with visible sidebar
>>    - Allow more width on small displays
>>    - Add padding to result text label
>
> test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java line 467:
> 
>> 465:         checkOutput("index-all.html", true,
>> 466:                 """
>> 467:                     <a href="pkg2/Foo.html#method(java.util.Vector)" class="member-name-link">method(Vector&lt;Object&gt;)</a>"""
> 
> Is this caused by replacing `Util.flatSignature` with `makeSignature(.., false, true)`?

Yes.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23666#discussion_r1996997122

From liach at openjdk.org  Sat Mar 15 16:21:59 2025
From: liach at openjdk.org (Chen Liang)
Date: Sat, 15 Mar 2025 16:21:59 GMT
Subject: RFR: 8345555: Improve layout of search results [v11]
In-Reply-To: <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>
Message-ID: <VTnGQoEEfriCJ1qIQiupLfUhHpPyhvSfFb1QQ8kv0wc=.556fbbeb-7587-4a0b-ae68-a0930565506f@github.com>

On Sat, 15 Mar 2025 06:48:52 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
>> 
>> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>> 
>> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>> 
>> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>> 
>> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
>> 
>> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>> 
>> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to ...
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix maximum size for search menu
>    - Correctly calculate available vertical space
>    - Align width with page content with visible sidebar
>    - Allow more width on small displays
>    - Add padding to result text label

Marked as reviewed by liach (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/23666#pullrequestreview-2687984553

From hannesw at openjdk.org  Mon Mar 17 09:03:05 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 17 Mar 2025 09:03:05 GMT
Subject: Integrated: 8345555: Improve layout of search results
In-Reply-To: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
Message-ID: <i_Zu0IfcjjpOzFLReyYTzeY2T3X9BnBaZsB4ndSYHZE=.905925e9-1c8f-4fae-a28f-33b0e5a2a3bd@github.com>

On Mon, 17 Feb 2025 14:46:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
> 
> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
> 
> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
> 
> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
> 
> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
> 
> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
> 
> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to the code so it will be eas...

This pull request has now been integrated.

Changeset: c8913d2c
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/c8913d2c9cd2ec522dc660cce01eb555e95dc775
Stats:     1089 lines in 33 files changed: 562 ins; 145 del; 382 mod

8345555: Improve layout of search results

Reviewed-by: liach, nbenalla

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

PR: https://git.openjdk.org/jdk/pull/23666

From hannesw at openjdk.org  Mon Mar 17 09:03:04 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 17 Mar 2025 09:03:04 GMT
Subject: RFR: 8345555: Improve layout of search results [v11]
In-Reply-To: <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>
References: <qqe87hKggeX6BvT0U5G_zILkeIqnebLmNFpUo_ySZUk=.341bf172-bd12-4476-84ca-475c3371eb6b@github.com>
 <n3iSCFfqwGMSiRDGDLzGU3jbA4cDCAmHFuGN9oWIk6Q=.2098f212-a64f-4f96-8cd6-eccf9f8ab8c4@github.com>
Message-ID: <mQRRwxLA3yy9oVne74Kuj7bKdZL6qGOV2R72LT6IA3g=.94e6c6ff-f848-4430-a0ab-a014640ea5b0@github.com>

On Sat, 15 Mar 2025 06:48:52 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to JavaDoc search to provide more context and a nicer layout for search results. This adds a new "kind" field to the search index to describes search items, such as "Static method", "Interface, or "System property" etc. Additionally, the drop-down search box uses a new two-column layout for search results to display this information. Previously we always displayed fully qualified names and signatures, now we mostly display simple names except if the user entered a qualified search term. 
>> 
>> The screenshot below shows an example of the new layout, you can of course [test the feature yourself](https://cr.openjdk.org/~hannesw/8345555/api.03/) (top-level files only). Note that the change affects moslty the drop-down search menu, the standalone search page was slightly updated to work with the new data but is otherwise unchanged.
>> 
>> <img width="659" alt="Screenshot 2025-02-17 at 14 56 52" src="https://github.com/user-attachments/assets/fb88a839-d3f8-4a27-957a-f1158b3ecff8" />
>> 
>> On the Java side, the feature is implemented by adding a new `IndexItem.Kind` enum class listing all possible kinds of index items, which include API `Element`s, JavaDoc tags and summary pages. The purpose if this enum is to send its `ordinal`s to the browser via JSON where it is used as array index into an array of localized messages. This means that the Java enum and JavaScript array have to be kept in sync manually, but it's relatively rare that new language elements or JavaDoc tags get added so that shouldn't be a problem.
>> 
>> There is a small change in JavaDoc HTML output because "System property" and "External specification" are now kinds of tags and no longer used as descriptions. On index pages they are now listed as "System property in package foo" rather than "Search tag in package foo" with the description "System Tag" added in the next line. 
>> 
>> Only actual `{@index}` tags can now have a description, which continues to be added as second line in index pages. In search, the description is now appended to the search term separated by "-", which makes it more visible and allows it to be searched for: https://cr.openjdk.org/~hannesw/8345555/api.02/search.html?q=tool&c=searchTags
>> 
>> On the JavaScript side, changes went a bit further than originally planned. I finally fixed the format of constructors not to show the class name twice, which required some retuning of ranking of search results. I used this occasion to add lots of comments to ...
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix maximum size for search menu
>    - Correctly calculate available vertical space
>    - Align width with page content with visible sidebar
>    - Allow more width on small displays
>    - Add padding to result text label

Thanks!

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

PR Comment: https://git.openjdk.org/jdk/pull/23666#issuecomment-2728660010

From hannesw at openjdk.org  Mon Mar 17 16:51:04 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Mon, 17 Mar 2025 16:51:04 GMT
Subject: RFR: 8352151: Fix display issues in javadoc-generated docs
Message-ID: <BKX53JgzOkqZEiEpWY6COeattU25w9q4623JiOwrpNw=.1be24d93-c603-460f-ad33-c7b7b0a040bd@github.com>

Please review a patch to fix a number of display bugs in javadoc-generated documentation.

 -  Snippet copy button is transparent and can overlap with snippet content ([example][example-snippet])
 - After clicking on the second-to-last item in the sidebar, the last item is highlighted if the click triggers scrolling to the end of the page ([example][example-target])
 - No indentation on sidebar entries beyond the first two levels of hierarchy (only applies to [help page][example-indent])
 - (Minor) Add vertical margin to search page inputs so they look better when wrapped

[example-snippet]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/invoke/MethodHandle.html#asSpreader(int,java.lang.Class,int)
[example-target]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/Thread.Builder.html#start(java.lang.Runnable)
[example-indent]: https://download.java.net/java/early_access/jdk25/docs/api/help-doc.html

The sidebar highlighting script actually became simpler, which is great. The snippet copy button change is a bit more involved, because I had to change snippet layout to not overlay snippet content with the copy button, and make the button opaque. But the result is better than what we had before IMO. The other changes are simple one-liners.

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

Commit messages:
 - 8352151: Fix display issues in javadoc-generated docs

Changes: https://git.openjdk.org/jdk/pull/24083/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24083&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8352151
  Stats: 95 lines in 2 files changed: 19 ins; 45 del; 31 mod
  Patch: https://git.openjdk.org/jdk/pull/24083.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24083/head:pull/24083

PR: https://git.openjdk.org/jdk/pull/24083

From hannesw at openjdk.org  Tue Mar 18 17:05:44 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 18 Mar 2025 17:05:44 GMT
Subject: RFR: 8352249: Remove incidental whitespace in traditional doc comments
Message-ID: <7U7VUjG-qIfM5AkHx7SaPnoh_rRBkxBl-et2TYzZ6VQ=.01406987-8cd8-4385-8945-92fb7b3f568d@github.com>

Please review a patch to remove incidental indentation from traditional doc comments. This adds a `stripIndent()` method to the `Tokens.Comment` interface and a new `JavadocTokenizer.StrippedComment` nested class that implements indentation stripping while maintaining a map of position offsets to the original comment. 

While the patch changes `javadoc` output by removing leading whitespace, the change is generally not visible in the browser except in `<pre>` elements, which is the point of this enhancement. 

The change affects most tree positions in the AST checker tests in javac/doctree, but mostly does not affect the structure of the parsed trees, with the exception of `BreakIterator` tests in `FirstSentenceTest.java`. 

`BreakIterator` does not recognize `.\n` immediately followed by a lower case letter as sentence break, while it recognizes the break if the letter is an upper-case letter *or* if there is a space between the line break and the letter. I find this rule a bit peculiar but AFAICT we can't influence the behavior of `BreakIterator`, so I have added tests that cover both lower and upper-case behavior.

The source position lookup in the stripped comment is implemented by creating a new `OffsetMap` that translates from the stripped to the original comment, then using the original comment's `OffsetMap` to translate the position to the source file. `OffsetMap` is relatively lightweight (usually 2 `int[]` elements per comment paragraph), so the added overhead is not too bad. 

Inspired by [JDK-8305688](https://bugs.openjdk.org/browse/JDK-8305688) I did various test builds with restricted jobs and memory settings, but didn't notice any change in processing or memory overhead to API docs builds.

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

Commit messages:
 - Rename method
 - Update comment
 - Clean up code, add comments, tests and @bug id
 - Updated copyright year in testSourceTab breaks test
 - Update remaining doctree tests & copyright headers
 - Avoid losing the last of multiple trailing newlines in stripComment
 - Remove unnecessary variable
 - Don't rely on trailing newline
 - Strip indentation from traditional doc comments

Changes: https://git.openjdk.org/jdk/pull/24032/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24032&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8352249
  Stats: 1386 lines in 63 files changed: 268 ins; 5 del; 1113 mod
  Patch: https://git.openjdk.org/jdk/pull/24032.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24032/head:pull/24032

PR: https://git.openjdk.org/jdk/pull/24032

From hannesw at openjdk.org  Wed Mar 19 08:22:25 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 19 Mar 2025 08:22:25 GMT
Subject: RFR: 8352249: Remove incidental whitespace in traditional doc
 comments [v2]
In-Reply-To: <7U7VUjG-qIfM5AkHx7SaPnoh_rRBkxBl-et2TYzZ6VQ=.01406987-8cd8-4385-8945-92fb7b3f568d@github.com>
References: <7U7VUjG-qIfM5AkHx7SaPnoh_rRBkxBl-et2TYzZ6VQ=.01406987-8cd8-4385-8945-92fb7b3f568d@github.com>
Message-ID: <AErB5dwFRk0Ol1ah3S8TXKD7dA5BT8Na2yip9wNGAJQ=.46dc6987-0027-4201-abb3-ab4a812c549b@github.com>

> Please review a patch to remove incidental indentation from traditional doc comments. This adds a `stripIndent()` method to the `Tokens.Comment` interface and a new `JavadocTokenizer.StrippedComment` nested class that implements indentation stripping while maintaining a map of position offsets to the original comment. 
> 
> While the patch changes `javadoc` output by removing leading whitespace, the change is generally not visible in the browser except in `<pre>` elements, which is the point of this enhancement. 
> 
> The change affects most tree positions in the AST checker tests in javac/doctree, but mostly does not affect the structure of the parsed trees, with the exception of `BreakIterator` tests in `FirstSentenceTest.java`. 
> 
> `BreakIterator` does not recognize `.\n` immediately followed by a lower case letter as sentence break, while it recognizes the break if the letter is an upper-case letter *or* if there is a space between the line break and the letter. I find this rule a bit peculiar but AFAICT we can't influence the behavior of `BreakIterator`, so I have added tests that cover both lower and upper-case behavior.
> 
> The source position lookup in the stripped comment is implemented by creating a new `OffsetMap` that translates from the stripped to the original comment, then using the original comment's `OffsetMap` to translate the position to the source file. `OffsetMap` is relatively lightweight (usually 2 `int[]` elements per comment paragraph), so the added overhead is not too bad. 
> 
> Inspired by [JDK-8305688](https://bugs.openjdk.org/browse/JDK-8305688) I did various test builds with restricted jobs and memory settings, but didn't notice any change in processing or memory overhead to API docs builds.

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Whitespace normalization in PrettyCheck becomes simpler

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24032/files
  - new: https://git.openjdk.org/jdk/pull/24032/files/eb9a090c..1c21de77

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24032&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24032&range=00-01

  Stats: 55 lines in 3 files changed: 0 ins; 48 del; 7 mod
  Patch: https://git.openjdk.org/jdk/pull/24032.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24032/head:pull/24032

PR: https://git.openjdk.org/jdk/pull/24032

From hannesw at openjdk.org  Wed Mar 19 11:31:51 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 19 Mar 2025 11:31:51 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
Message-ID: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>

Please review a change to remove incidental whitespace commonly found at the beginning of `<pre><code>` or `<pre>{@code` tags. This patch is dependent on [JDK-8352249](https://bugs.openjdk.org/browse/JDK-8352249) and completes the removal of incidental whitespace in traditional doc comments. 

This is implemented by parsing content of `<pre>` elements into a separate list buffer in `DocCommentParser`, and filter the content for leading blank linkes when the element is closed. The decision to filter `<pre>` element contents only once the element is closed was made in order to be able to keep the logic in a single method without further complicating other parts of `DocCommentParser`.

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

Depends on: https://git.openjdk.org/jdk/pull/24032

Commit messages:
 - Improve test
 - Add comment
 - 8352389: Remove incidental whitespace in pre/code content

Changes: https://git.openjdk.org/jdk/pull/24112/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8352389
  Stats: 354 lines in 7 files changed: 342 ins; 3 del; 9 mod
  Patch: https://git.openjdk.org/jdk/pull/24112.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24112/head:pull/24112

PR: https://git.openjdk.org/jdk/pull/24112

From liach at openjdk.org  Wed Mar 19 23:33:13 2025
From: liach at openjdk.org (Chen Liang)
Date: Wed, 19 Mar 2025 23:33:13 GMT
Subject: RFR: 8352249: Remove incidental whitespace in traditional doc
 comments [v2]
In-Reply-To: <AErB5dwFRk0Ol1ah3S8TXKD7dA5BT8Na2yip9wNGAJQ=.46dc6987-0027-4201-abb3-ab4a812c549b@github.com>
References: <7U7VUjG-qIfM5AkHx7SaPnoh_rRBkxBl-et2TYzZ6VQ=.01406987-8cd8-4385-8945-92fb7b3f568d@github.com>
 <AErB5dwFRk0Ol1ah3S8TXKD7dA5BT8Na2yip9wNGAJQ=.46dc6987-0027-4201-abb3-ab4a812c549b@github.com>
Message-ID: <ZLaTVbyaHY4_fm7TRkDqi97IdWLx8DfQ1NiNPyv3mWw=.72eed97e-3a97-4972-8fb0-7baa19326d00@github.com>

On Wed, 19 Mar 2025 08:22:25 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a patch to remove incidental indentation from traditional doc comments, comparable to doing a `String.stripIndent()` on the comment contents but without special treatment of a last blank line. This adds a `stripIndent()` method to the `Tokens.Comment` interface and a new `JavadocTokenizer.StrippedComment` nested class that implements indentation stripping while maintaining a map of position offsets to the original comment. 
>> 
>> While the patch changes `javadoc` output by removing leading whitespace, the change is generally not visible in the browser except in `<pre>` elements, which is the point of this enhancement. 
>> 
>> The change affects most tree positions in the AST checker tests in javac/doctree, but mostly does not affect the structure of the parsed trees, with the exception of `BreakIterator` tests in `FirstSentenceTest.java`. 
>> 
>> `BreakIterator` does not recognize `.\n` immediately followed by a lower case letter as sentence break, while it recognizes the break if the letter is an upper-case letter *or* if there is a space between the line break and the letter. I find this rule a bit peculiar but AFAICT we can't influence the behavior of `BreakIterator`, so I have added tests that cover both lower and upper-case behavior.
>> 
>> The source position lookup in the stripped comment is implemented by creating a new `OffsetMap` that translates from the stripped to the original comment, then using the original comment's `OffsetMap` to translate the position to the source file. `OffsetMap` is relatively lightweight (usually 2 `int[]` elements per comment paragraph), so the added overhead is not too bad. 
>> 
>> Inspired by [JDK-8305688](https://bugs.openjdk.org/browse/JDK-8305688) I did various test builds with restricted jobs and memory settings, but didn't notice any change in processing or memory overhead to API docs builds.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Whitespace normalization in PrettyCheck becomes simpler

Looks good.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24032#pullrequestreview-2700546175

From hannesw at openjdk.org  Thu Mar 20 06:02:12 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Mar 2025 06:02:12 GMT
Subject: RFR: 8352249: Remove incidental whitespace in traditional doc
 comments [v2]
In-Reply-To: <AErB5dwFRk0Ol1ah3S8TXKD7dA5BT8Na2yip9wNGAJQ=.46dc6987-0027-4201-abb3-ab4a812c549b@github.com>
References: <7U7VUjG-qIfM5AkHx7SaPnoh_rRBkxBl-et2TYzZ6VQ=.01406987-8cd8-4385-8945-92fb7b3f568d@github.com>
 <AErB5dwFRk0Ol1ah3S8TXKD7dA5BT8Na2yip9wNGAJQ=.46dc6987-0027-4201-abb3-ab4a812c549b@github.com>
Message-ID: <-ORVCezfWrCYimEOORZHcheJusIrftPY9Mdt7xkGIWs=.54cd70b7-28f4-4fd0-a046-fa73a1d80efa@github.com>

On Wed, 19 Mar 2025 08:22:25 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a patch to remove incidental indentation from traditional doc comments, comparable to doing a `String.stripIndent()` on the comment contents but without special treatment of a last blank line. This adds a `stripIndent()` method to the `Tokens.Comment` interface and a new `JavadocTokenizer.StrippedComment` nested class that implements indentation stripping while maintaining a map of position offsets to the original comment. 
>> 
>> While the patch changes `javadoc` output by removing leading whitespace, the change is generally not visible in the browser except in `<pre>` elements, which is the point of this enhancement. 
>> 
>> The change affects most tree positions in the AST checker tests in javac/doctree, but mostly does not affect the structure of the parsed trees, with the exception of `BreakIterator` tests in `FirstSentenceTest.java`. 
>> 
>> `BreakIterator` does not recognize `.\n` immediately followed by a lower case letter as sentence break, while it recognizes the break if the letter is an upper-case letter *or* if there is a space between the line break and the letter. I find this rule a bit peculiar but AFAICT we can't influence the behavior of `BreakIterator`, so I have added tests that cover both lower and upper-case behavior.
>> 
>> The source position lookup in the stripped comment is implemented by creating a new `OffsetMap` that translates from the stripped to the original comment, then using the original comment's `OffsetMap` to translate the position to the source file. `OffsetMap` is relatively lightweight (usually 2 `int[]` elements per comment paragraph), so the added overhead is not too bad. 
>> 
>> Inspired by [JDK-8305688](https://bugs.openjdk.org/browse/JDK-8305688) I did various test builds with restricted jobs and memory settings, but didn't notice any change in processing or memory overhead to API docs builds.
>
> Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Whitespace normalization in PrettyCheck becomes simpler

Thanks!

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

PR Comment: https://git.openjdk.org/jdk/pull/24032#issuecomment-2739289037

From hannesw at openjdk.org  Thu Mar 20 06:02:13 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Mar 2025 06:02:13 GMT
Subject: Integrated: 8352249: Remove incidental whitespace in traditional doc
 comments
In-Reply-To: <7U7VUjG-qIfM5AkHx7SaPnoh_rRBkxBl-et2TYzZ6VQ=.01406987-8cd8-4385-8945-92fb7b3f568d@github.com>
References: <7U7VUjG-qIfM5AkHx7SaPnoh_rRBkxBl-et2TYzZ6VQ=.01406987-8cd8-4385-8945-92fb7b3f568d@github.com>
Message-ID: <PL4DujhukqLsKk618AijOEnPRh6oma5Pm6ioSerYrjg=.9566f30a-8f81-43ae-9d24-ab572cb71a26@github.com>

On Thu, 13 Mar 2025 13:12:10 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a patch to remove incidental indentation from traditional doc comments, comparable to doing a `String.stripIndent()` on the comment contents but without special treatment of a last blank line. This adds a `stripIndent()` method to the `Tokens.Comment` interface and a new `JavadocTokenizer.StrippedComment` nested class that implements indentation stripping while maintaining a map of position offsets to the original comment. 
> 
> While the patch changes `javadoc` output by removing leading whitespace, the change is generally not visible in the browser except in `<pre>` elements, which is the point of this enhancement. 
> 
> The change affects most tree positions in the AST checker tests in javac/doctree, but mostly does not affect the structure of the parsed trees, with the exception of `BreakIterator` tests in `FirstSentenceTest.java`. 
> 
> `BreakIterator` does not recognize `.\n` immediately followed by a lower case letter as sentence break, while it recognizes the break if the letter is an upper-case letter *or* if there is a space between the line break and the letter. I find this rule a bit peculiar but AFAICT we can't influence the behavior of `BreakIterator`, so I have added tests that cover both lower and upper-case behavior.
> 
> The source position lookup in the stripped comment is implemented by creating a new `OffsetMap` that translates from the stripped to the original comment, then using the original comment's `OffsetMap` to translate the position to the source file. `OffsetMap` is relatively lightweight (usually 2 `int[]` elements per comment paragraph), so the added overhead is not too bad. 
> 
> Inspired by [JDK-8305688](https://bugs.openjdk.org/browse/JDK-8305688) I did various test builds with restricted jobs and memory settings, but didn't notice any change in processing or memory overhead to API docs builds.

This pull request has now been integrated.

Changeset: a5d06a18
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/a5d06a18762c81eda5883c07b42621278b9209c9
Stats:     1438 lines in 64 files changed: 268 ins; 53 del; 1117 mod

8352249: Remove incidental whitespace in traditional doc comments

Reviewed-by: liach

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

PR: https://git.openjdk.org/jdk/pull/24032

From hannesw at openjdk.org  Thu Mar 20 06:07:47 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Mar 2025 06:07:47 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
 [v2]
In-Reply-To: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
Message-ID: <-fUZ7sCv8Q02u6hd6m_jMJbDGHdn_4Ix4Z-hJlTYWkQ=.8166f84e-fd35-4950-9916-d017dceefdde@github.com>

> Please review a change to remove incidental whitespace commonly found at the beginning of `<pre><code>` or `<pre>{@code` tags. This patch is dependent on [JDK-8352249](https://bugs.openjdk.org/browse/JDK-8352249) and completes the removal of incidental whitespace in traditional doc comments. 
> 
> This is implemented by parsing content of `<pre>` elements into a separate list buffer in `DocCommentParser`, and filter the content for leading blank linkes when the element is closed. The decision to filter `<pre>` element contents only once the element is closed was made in order to be able to keep the logic in a single method without further complicating other parts of `DocCommentParser`.

Hannes Walln?fer 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.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24112/files
  - new: https://git.openjdk.org/jdk/pull/24112/files/e3ded45f..e3ded45f

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=00-01

  Stats: 0 lines in 0 files changed: 0 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/24112.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24112/head:pull/24112

PR: https://git.openjdk.org/jdk/pull/24112

From hannesw at openjdk.org  Thu Mar 20 07:27:39 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Mar 2025 07:27:39 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
 [v3]
In-Reply-To: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
Message-ID: <ubUk0MkY770qWlGfBRpNAsP94bO9zdy42MKaESSGvtw=.4b01189a-d21e-476f-8580-e5b4f9787ddd@github.com>

> Please review a change to remove incidental whitespace commonly found at the beginning of `<pre><code>` or `<pre>{@code` tags. This patch is dependent on [JDK-8352249](https://bugs.openjdk.org/browse/JDK-8352249) and completes the removal of incidental whitespace in traditional doc comments. 
> 
> This is implemented by parsing content of `<pre>` elements into a separate list buffer in `DocCommentParser`, and filter the content for leading blank linkes when the element is closed. The decision to filter `<pre>` element contents only once the element is closed was made in order to be able to keep the logic in a single method without further complicating other parts of `DocCommentParser`.

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 14 commits:

 - Merge branch 'master' into JDK-8352389
 - Improve test
 - Add comment
 - 8352389: Remove incidental whitespace in pre/code content
 - Whitespace normalization in PrettyCheck becomes simpler
 - Rename method
 - Update comment
 - Clean up code, add comments, tests and @bug id
 - Updated copyright year in testSourceTab breaks test
 - Update remaining doctree tests & copyright headers
 - ... and 4 more: https://git.openjdk.org/jdk/compare/fb210e3a...5ec3bc04

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

Changes: https://git.openjdk.org/jdk/pull/24112/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=02
  Stats: 354 lines in 7 files changed: 342 ins; 3 del; 9 mod
  Patch: https://git.openjdk.org/jdk/pull/24112.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24112/head:pull/24112

PR: https://git.openjdk.org/jdk/pull/24112

From hannesw at openjdk.org  Thu Mar 20 17:37:51 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 20 Mar 2025 17:37:51 GMT
Subject: RFR: 8352511: Show additional level of headings in table of contents
Message-ID: <NgfuR7aHPzohM0RyGYM7Cuw3wET_b6y5TFyerRIrDvQ=.794814f9-5154-4405-949c-8ada51c9a779@github.com>

Please review a patch to show an additional level of headings in the table of contents for module, package and class descriptions. Previously only `<h2>` headings were shown in the table of contents, now we also show `<h3>` level headings.

The `TableOfContents` class no longer provides `pushNestedList`/`popNestedList` methods that require us to manually manage nesting level. Instead, the method to add a TOC entry gets an additional `level` parameter with an enum type to specify the nesting level (`FIRST`, `SECOND`, `THIRD`). The class will then configure the list to the desired nesting level before adding the entry. Of course this works with both tradidtional and Markdown doc comments and has tests for both.

There are not too many API elements in JDK that use `<h3>` level headings, but those that do benefit a lot from this change. A few examples:

 - [package java.util.stream](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/util/stream/package-summary.html)
 - [package java.lang.classfile](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/classfile/package-summary.html)
 - [package java.lang.invoke](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/invoke/package-summary.html)
 - [package java.lang.module](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/module/package-summary.html)

This PR depends on #24083 not for technical reasons but because that PR fixes the rendering of the third level of TOC entries.

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

Depends on: https://git.openjdk.org/jdk/pull/24083

Commit messages:
 - Remove trailing whitespace
 - 8352511: Show additional level of headings in table of contents

Changes: https://git.openjdk.org/jdk/pull/24137/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24137&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8352511
  Stats: 348 lines in 19 files changed: 240 ins; 44 del; 64 mod
  Patch: https://git.openjdk.org/jdk/pull/24137.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24137/head:pull/24137

PR: https://git.openjdk.org/jdk/pull/24137

From hannesw at openjdk.org  Fri Mar 21 03:12:39 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Mar 2025 03:12:39 GMT
Subject: RFR: 8352511: Show additional level of headings in table of
 contents [v2]
In-Reply-To: <NgfuR7aHPzohM0RyGYM7Cuw3wET_b6y5TFyerRIrDvQ=.794814f9-5154-4405-949c-8ada51c9a779@github.com>
References: <NgfuR7aHPzohM0RyGYM7Cuw3wET_b6y5TFyerRIrDvQ=.794814f9-5154-4405-949c-8ada51c9a779@github.com>
Message-ID: <KM9aShyEHCkS6bxPwm9YvnrPuyEk2ztXgqYC3857kqI=.556cd970-e316-446e-a8dc-40cde6ad985b@github.com>

> Please review a patch to show an additional level of headings in the table of contents for module, package and class descriptions. Previously only `<h2>` headings were shown in the table of contents, now we also show `<h3>` level headings.
> 
> The `TableOfContents` class no longer provides `pushNestedList`/`popNestedList` methods that require us to manually manage nesting level. Instead, the method to add a TOC entry gets an additional `level` parameter with an enum type to specify the nesting level (`FIRST`, `SECOND`, `THIRD`). The class will then configure the list to the desired nesting level before adding the entry. Of course this works with both tradidtional and Markdown doc comments and has tests for both.
> 
> There are not too many API elements in JDK that use `<h3>` level headings, but those that do benefit a lot from this change. A few examples:
> 
>  - [package java.util.stream](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/util/stream/package-summary.html)
>  - [package java.lang.classfile](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/classfile/package-summary.html)
>  - [package java.lang.invoke](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/invoke/package-summary.html)
>  - [package java.lang.module](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/module/package-summary.html)
> 
> This PR depends on #24083 not for technical reasons but because that PR fixes the rendering of the third level of TOC entries.

Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:

 - Update copyright headers
 - Update ListBuilder

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24137/files
  - new: https://git.openjdk.org/jdk/pull/24137/files/917737d8..6ae180c1

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24137&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24137&range=00-01

  Stats: 32 lines in 14 files changed: 0 ins; 9 del; 23 mod
  Patch: https://git.openjdk.org/jdk/pull/24137.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24137/head:pull/24137

PR: https://git.openjdk.org/jdk/pull/24137

From liach at openjdk.org  Fri Mar 21 05:09:05 2025
From: liach at openjdk.org (Chen Liang)
Date: Fri, 21 Mar 2025 05:09:05 GMT
Subject: RFR: 8352151: Fix display issues in javadoc-generated docs
In-Reply-To: <BKX53JgzOkqZEiEpWY6COeattU25w9q4623JiOwrpNw=.1be24d93-c603-460f-ad33-c7b7b0a040bd@github.com>
References: <BKX53JgzOkqZEiEpWY6COeattU25w9q4623JiOwrpNw=.1be24d93-c603-460f-ad33-c7b7b0a040bd@github.com>
Message-ID: <wjmseAOp8hWcRmrG-GCdvSqSfA5Wa1TSTFiGU5h5I5I=.4fbaaf84-9a18-4d4d-885d-2651028e319f@github.com>

On Mon, 17 Mar 2025 16:06:58 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a patch to fix a number of display bugs in javadoc-generated documentation.
> 
>  -  Snippet copy button is transparent and can overlap with snippet content ([before][snippet-before], [after][snippet-after])
>  - After clicking on the second-to-last item in the sidebar, the last item is highlighted if the click triggers scrolling to the end of the page ([before][target-before], [after][target-after])
>  - No indentation on sidebar entries beyond the first two levels of hierarchy ([before][indent-before], [after][indent-after])
>  - (Minor) Add vertical margin to search page inputs so they look better when wrapped
> 
> [snippet-before]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/invoke/MethodHandle.html#asSpreader(int,java.lang.Class,int)
> [snippet-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/java.base/java/lang/invoke/MethodHandle.html#asSpreader(int,java.lang.Class,int)
> 
> [target-before]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/Thread.Builder.html#start(java.lang.Runnable)
> [target-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/java.base/java/lang/Thread.Builder.html#start(java.lang.Runnable)
> 
> [indent-before]: https://download.java.net/java/early_access/jdk25/docs/api/help-doc.html
> [indent-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/help-doc.html
> 
> The sidebar highlighting script actually became simpler, which is great. The snippet copy button change is a bit more involved, because I had to change snippet layout to not overlay snippet content with the copy button, and make the button opaque. But the result is better than what we had before IMO. The other changes are simple one-liners.

The js part looks good. Not too sure about the CSS, @nizarbenalla might check too. The rendered effects look good.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24083#pullrequestreview-2704748162

From liach at openjdk.org  Fri Mar 21 05:20:10 2025
From: liach at openjdk.org (Chen Liang)
Date: Fri, 21 Mar 2025 05:20:10 GMT
Subject: RFR: 8352511: Show additional level of headings in table of
 contents [v2]
In-Reply-To: <KM9aShyEHCkS6bxPwm9YvnrPuyEk2ztXgqYC3857kqI=.556cd970-e316-446e-a8dc-40cde6ad985b@github.com>
References: <NgfuR7aHPzohM0RyGYM7Cuw3wET_b6y5TFyerRIrDvQ=.794814f9-5154-4405-949c-8ada51c9a779@github.com>
 <KM9aShyEHCkS6bxPwm9YvnrPuyEk2ztXgqYC3857kqI=.556cd970-e316-446e-a8dc-40cde6ad985b@github.com>
Message-ID: <v6iFKUq8UDUnQV4SgXc5IhkVKCXJwgnKZCDt4XK-KoY=.1a790fc0-e1b9-448b-b0a8-36bb115355c1@github.com>

On Fri, 21 Mar 2025 03:12:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a patch to show an additional level of headings in the table of contents for module, package and class descriptions. Previously only `<h2>` headings were shown in the table of contents, now we also show `<h3>` level headings.
>> 
>> The `TableOfContents` class no longer provides `pushNestedList`/`popNestedList` methods that require us to manually manage nesting level. Instead, the method to add a TOC entry gets an additional `level` parameter with an enum type to specify the nesting level (`FIRST`, `SECOND`, `THIRD`). The class will then configure the list to the desired nesting level before adding the entry. Of course this works with both tradidtional and Markdown doc comments and has tests for both.
>> 
>> There are not too many API elements in JDK that use `<h3>` level headings, but those that do benefit a lot from this change. A few examples:
>> 
>>  - [package java.util.stream](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/util/stream/package-summary.html)
>>  - [package java.lang.classfile](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/classfile/package-summary.html)
>>  - [package java.lang.invoke](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/invoke/package-summary.html)
>>  - [package java.lang.module](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/module/package-summary.html)
>> 
>> This PR depends on #24083 not for technical reasons but because that PR fixes the rendering of the third level of TOC entries.
>
> Hannes Walln?fer has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Update copyright headers
>  - Update ListBuilder

Looks good. Since the removal of old push/pop will cause compile errors, I assume you have updated all legacy sites.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24137#pullrequestreview-2704760704

From hannesw at openjdk.org  Fri Mar 21 05:59:15 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Mar 2025 05:59:15 GMT
Subject: RFR: 8352511: Show additional level of headings in table of
 contents [v2]
In-Reply-To: <v6iFKUq8UDUnQV4SgXc5IhkVKCXJwgnKZCDt4XK-KoY=.1a790fc0-e1b9-448b-b0a8-36bb115355c1@github.com>
References: <NgfuR7aHPzohM0RyGYM7Cuw3wET_b6y5TFyerRIrDvQ=.794814f9-5154-4405-949c-8ada51c9a779@github.com>
 <KM9aShyEHCkS6bxPwm9YvnrPuyEk2ztXgqYC3857kqI=.556cd970-e316-446e-a8dc-40cde6ad985b@github.com>
 <v6iFKUq8UDUnQV4SgXc5IhkVKCXJwgnKZCDt4XK-KoY=.1a790fc0-e1b9-448b-b0a8-36bb115355c1@github.com>
Message-ID: <LbYNJGnE5YVpR3NXQdqZ576HFCb8u9gYF_HzwoMj9MI=.61109c96-44b2-4142-93ea-8ef49f2919ad@github.com>

On Fri, 21 Mar 2025 05:17:58 GMT, Chen Liang <liach at openjdk.org> wrote:

> Looks good. Since the removal of old push/pop will cause compile errors, I assume you have updated all legacy sites.

This is an internal API that was created specifically for this use and isn't used anywhere else, so we should be fine.

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

PR Comment: https://git.openjdk.org/jdk/pull/24137#issuecomment-2742387724

From hannesw at openjdk.org  Fri Mar 21 06:10:12 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Mar 2025 06:10:12 GMT
Subject: RFR: 8352389: Remove incidental whitespace in pre/code content
 [v3]
In-Reply-To: <ubUk0MkY770qWlGfBRpNAsP94bO9zdy42MKaESSGvtw=.4b01189a-d21e-476f-8580-e5b4f9787ddd@github.com>
References: <_nIhYXPaNlvsFHzHejW-nHWfSubHnTRN2OqLqbyOj00=.e3f2b677-512f-413c-b26d-7996275a986d@github.com>
 <ubUk0MkY770qWlGfBRpNAsP94bO9zdy42MKaESSGvtw=.4b01189a-d21e-476f-8580-e5b4f9787ddd@github.com>
Message-ID: <IsnO0bAhxCPy5U7PXUhkCvpLceqIWvgymQAimJ27rcs=.ede22cc8-30b2-4407-8bee-9e973bdfee76@github.com>

On Thu, 20 Mar 2025 07:27:39 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a change to remove incidental whitespace commonly found at the beginning of combined `pre` and `code` tags. 
>> 
>> In a nutshell, using `<pre><code>\n` or `<pre>{@code\n` at the beginning of preformatted code adds an extra empty line at the beginning of the content, compared to just using `<pre>\n`. This is due to [HTML syntax rules](https://html.spec.whatwg.org/#the-pre-element:the-pre-element) and needlessly complicates use of these tags in doc comments. 
>> 
>> This change does the minimum necessary to remove the leading line break. What makes the task slightly more complicated is that we also have to remove any horizontal whitespace between `pre` and `code` tags as these would otherwise add indentation to the first line of actual pre content.
>> 
>> This is implemented by parsing content of `<pre>` elements into a separate list buffer in `DocCommentParser`, and filtering the content when we encounter the `</pre>` close tag. This approach allows us to keep the logic in a single `normalizePreContent` method instead of spreading it in various existing places of `DocCommentParser`. The method uses a `DocTreeVisitor` in combination with a `State` enum to make sure pre content is only modified if all conditions are met (which involves inspecting up to the first three DocTrees).
>> 
>> Normalization is also performed in `<pre>{@literal\n`. Although `{@literal}` by itself does not cause the problem described above as it does not produce an HTML tag, any horizontal whitespace between `<pre>` and `{@literal` will cause the problem, so we err on the side of caution.
>
> 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 14 commits:
> 
>  - Merge branch 'master' into JDK-8352389
>  - Improve test
>  - Add comment
>  - 8352389: Remove incidental whitespace in pre/code content
>  - Whitespace normalization in PrettyCheck becomes simpler
>  - Rename method
>  - Update comment
>  - Clean up code, add comments, tests and @bug id
>  - Updated copyright year in testSourceTab breaks test
>  - Update remaining doctree tests & copyright headers
>  - ... and 4 more: https://git.openjdk.org/jdk/compare/fb210e3a...5ec3bc04

Note: Github shows 14 commits for this PR, but the first 10 belong to #24032, on which this PR depended and which has already been integrated. Only the last 4 commits actually belong to this PR.

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

PR Comment: https://git.openjdk.org/jdk/pull/24112#issuecomment-2742416198

From nbenalla at openjdk.org  Fri Mar 21 11:31:07 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 21 Mar 2025 11:31:07 GMT
Subject: RFR: 8352151: Fix display issues in javadoc-generated docs
In-Reply-To: <BKX53JgzOkqZEiEpWY6COeattU25w9q4623JiOwrpNw=.1be24d93-c603-460f-ad33-c7b7b0a040bd@github.com>
References: <BKX53JgzOkqZEiEpWY6COeattU25w9q4623JiOwrpNw=.1be24d93-c603-460f-ad33-c7b7b0a040bd@github.com>
Message-ID: <EGebGqpnqScFHZVXsm0GqcU4zjVNpK-LJ5WTxXsIZiE=.6c20f45f-e3c1-4758-a282-a3bbaf6dcb0e@github.com>

On Mon, 17 Mar 2025 16:06:58 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a patch to fix a number of display bugs in javadoc-generated documentation.
> 
>  -  Snippet copy button is transparent and can overlap with snippet content ([before][snippet-before], [after][snippet-after])
>  - After clicking on the second-to-last item in the sidebar, the last item is highlighted if the click triggers scrolling to the end of the page ([before][target-before], [after][target-after])
>  - No indentation on sidebar entries beyond the first two levels of hierarchy ([before][indent-before], [after][indent-after])
>  - (Minor) Add vertical margin to search page inputs so they look better when wrapped
> 
> [snippet-before]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/invoke/MethodHandle.html#asSpreader(int,java.lang.Class,int)
> [snippet-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/java.base/java/lang/invoke/MethodHandle.html#asSpreader(int,java.lang.Class,int)
> 
> [target-before]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/Thread.Builder.html#start(java.lang.Runnable)
> [target-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/java.base/java/lang/Thread.Builder.html#start(java.lang.Runnable)
> 
> [indent-before]: https://download.java.net/java/early_access/jdk25/docs/api/help-doc.html
> [indent-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/help-doc.html
> 
> The sidebar highlighting script actually became simpler, which is great. The snippet copy button change is a bit more involved, because I had to change snippet layout to not overlay snippet content with the copy button, and make the button opaque. But the result is better than what we had before IMO. The other changes are simple one-liners.

Looks good.

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

Marked as reviewed by nbenalla (Committer).

PR Review: https://git.openjdk.org/jdk/pull/24083#pullrequestreview-2705599810

From hannesw at openjdk.org  Fri Mar 21 11:53:28 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Mar 2025 11:53:28 GMT
Subject: Integrated: 8352151: Fix display issues in javadoc-generated docs
In-Reply-To: <BKX53JgzOkqZEiEpWY6COeattU25w9q4623JiOwrpNw=.1be24d93-c603-460f-ad33-c7b7b0a040bd@github.com>
References: <BKX53JgzOkqZEiEpWY6COeattU25w9q4623JiOwrpNw=.1be24d93-c603-460f-ad33-c7b7b0a040bd@github.com>
Message-ID: <ECJaVKPs79G1Twe7tw5QKqZDFNlFKsucvxV52V8d0CE=.b7b1a3c3-0209-4398-8fea-c740d18c5a60@github.com>

On Mon, 17 Mar 2025 16:06:58 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a patch to fix a number of display bugs in javadoc-generated documentation.
> 
>  -  Snippet copy button is transparent and can overlap with snippet content ([before][snippet-before], [after][snippet-after])
>  - After clicking on the second-to-last item in the sidebar, the last item is highlighted if the click triggers scrolling to the end of the page ([before][target-before], [after][target-after])
>  - No indentation on sidebar entries beyond the first two levels of hierarchy ([before][indent-before], [after][indent-after])
>  - (Minor) Add vertical margin to search page inputs so they look better when wrapped
> 
> [snippet-before]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/invoke/MethodHandle.html#asSpreader(int,java.lang.Class,int)
> [snippet-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/java.base/java/lang/invoke/MethodHandle.html#asSpreader(int,java.lang.Class,int)
> 
> [target-before]: https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/lang/Thread.Builder.html#start(java.lang.Runnable)
> [target-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/java.base/java/lang/Thread.Builder.html#start(java.lang.Runnable)
> 
> [indent-before]: https://download.java.net/java/early_access/jdk25/docs/api/help-doc.html
> [indent-after]: https://cr.openjdk.org/~hannesw/8352151/api.00/help-doc.html
> 
> The sidebar highlighting script actually became simpler, which is great. The snippet copy button change is a bit more involved, because I had to change snippet layout to not overlay snippet content with the copy button, and make the button opaque. But the result is better than what we had before IMO. The other changes are simple one-liners.

This pull request has now been integrated.

Changeset: 28250f83
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/28250f83b728c9b3395d9c4858568a3603172b8a
Stats:     95 lines in 2 files changed: 19 ins; 45 del; 31 mod

8352151: Fix display issues in javadoc-generated docs

Reviewed-by: liach, nbenalla

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

PR: https://git.openjdk.org/jdk/pull/24083

From nbenalla at openjdk.org  Mon Mar 24 14:55:50 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 24 Mar 2025 14:55:50 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index
Message-ID: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>

Please review this patch to fix an issue in the `tag-search-index.js` generation.

The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.

TIA

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

Commit messages:
 - fix bug related to line breaks in json

Changes: https://git.openjdk.org/jdk/pull/24202/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24202&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8351332
  Stats: 85 lines in 2 files changed: 84 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/24202.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24202/head:pull/24202

PR: https://git.openjdk.org/jdk/pull/24202

From liach at openjdk.org  Mon Mar 24 16:12:14 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 24 Mar 2025 16:12:14 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index
In-Reply-To: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
Message-ID: <sll0q60s47RYYy6pAu83OqcsX1HdWCnJdhCCPrcFdRg=.1303359d-ccc2-426c-8a1d-1012c55cfd77@github.com>

On Mon, 24 Mar 2025 14:41:43 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this patch to fix an issue in the `tag-search-index.js` generation.
> 
> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
> 
> TIA

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexItem.java line 645:

> 643:                 if (!description.isEmpty()) {
> 644:                     String normalizedDescription = description.replaceAll("\\s+", " ");
> 645:                     builder.append("d", escapeQuotes(normalizedDescription));

Should we just handle all whitespaces in `escapeQuotes`?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24202#discussion_r2010492415

From nbenalla at openjdk.org  Mon Mar 24 16:17:15 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 24 Mar 2025 16:17:15 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index
In-Reply-To: <sll0q60s47RYYy6pAu83OqcsX1HdWCnJdhCCPrcFdRg=.1303359d-ccc2-426c-8a1d-1012c55cfd77@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <sll0q60s47RYYy6pAu83OqcsX1HdWCnJdhCCPrcFdRg=.1303359d-ccc2-426c-8a1d-1012c55cfd77@github.com>
Message-ID: <xYsoxNiTKhPW-CwCMCGPPnUd9w48FD5lNVNVY29pLwU=.1d72bade-6c2c-4d99-9f86-b518a6015485@github.com>

On Mon, 24 Mar 2025 16:09:20 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Please review this patch to fix an issue in the `tag-search-index.js` generation.
>> 
>> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
>> 
>> TIA
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexItem.java line 645:
> 
>> 643:                 if (!description.isEmpty()) {
>> 644:                     String normalizedDescription = description.replaceAll("\\s+", " ");
>> 645:                     builder.append("d", escapeQuotes(normalizedDescription));
> 
> Should we just handle all whitespaces in `escapeQuotes`?

I thought about it but that may not be necessary because the other json keys (`l`, `h`, `u`) cannot have whitespace in them.

I'm not opposed to handing whitespace in an `escapeQuotesAndWhitespace` method though.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24202#discussion_r2010502316

From liach at openjdk.org  Mon Mar 24 16:42:14 2025
From: liach at openjdk.org (Chen Liang)
Date: Mon, 24 Mar 2025 16:42:14 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index
In-Reply-To: <xYsoxNiTKhPW-CwCMCGPPnUd9w48FD5lNVNVY29pLwU=.1d72bade-6c2c-4d99-9f86-b518a6015485@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <sll0q60s47RYYy6pAu83OqcsX1HdWCnJdhCCPrcFdRg=.1303359d-ccc2-426c-8a1d-1012c55cfd77@github.com>
 <xYsoxNiTKhPW-CwCMCGPPnUd9w48FD5lNVNVY29pLwU=.1d72bade-6c2c-4d99-9f86-b518a6015485@github.com>
Message-ID: <qGVbV67-TTut2nSHNsTOgAk6mCpApWmPVlVvXc14jtg=.9db9180c-c8a8-4510-acb2-aea7249331df@github.com>

On Mon, 24 Mar 2025 16:14:54 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/IndexItem.java line 645:
>> 
>>> 643:                 if (!description.isEmpty()) {
>>> 644:                     String normalizedDescription = description.replaceAll("\\s+", " ");
>>> 645:                     builder.append("d", escapeQuotes(normalizedDescription));
>> 
>> Should we just handle all whitespaces in `escapeQuotes`?
>
> I thought about it but that may not be necessary because the other json keys (`l`, `h`, `u`) cannot have whitespace in them.
> 
> I'm not opposed to handing whitespace in an `escapeQuotesAndWhitespace` method though.

I think we should have one that escapes spaces and another that fails on spaces to replace the current escapeQuotes.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24202#discussion_r2010551795

From nbenalla at openjdk.org  Mon Mar 24 17:16:07 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Mon, 24 Mar 2025 17:16:07 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG
Message-ID: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>

Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.

Previously, all uses of `HtmlTag.IMG` followed a similar pattern :

HtmlTree.of(HtmlTag.IMG)
                        .put(HtmlAttr.SRC, docpath)
                        .put(HtmlAttr.ALT, alt)


However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.

No tests are required as part of this change.

TIA

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

Commit messages:
 - add new factory method HtmlTree IMG(DocPath src, String alt)

Changes: https://git.openjdk.org/jdk/pull/24204/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=24204&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8352740
  Stats: 29 lines in 4 files changed: 12 ins; 7 del; 10 mod
  Patch: https://git.openjdk.org/jdk/pull/24204.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24204/head:pull/24204

PR: https://git.openjdk.org/jdk/pull/24204

From liach at openjdk.org  Tue Mar 25 03:15:08 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 25 Mar 2025 03:15:08 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v2]
In-Reply-To: <RgmwHD6t4dj1q6gSOcn37xIaxP7FIceOxBHdqcI8cCo=.3fabacf1-3b3a-470e-9e41-af1b23017abc@github.com>
References: <dX1QjYZMvLqrR9bS1YLuvpWlXWTcCo56grLUDgh59Pg=.f908cdb2-911a-4ca3-b86e-a07d86a92a6e@github.com>
 <RgmwHD6t4dj1q6gSOcn37xIaxP7FIceOxBHdqcI8cCo=.3fabacf1-3b3a-470e-9e41-af1b23017abc@github.com>
Message-ID: <TuRAJRlC3CNXcQiQy6HYRdVtD9uZL3x9O-O5gVbX8Js=.66b5ec13-b46f-4892-8b7f-f7ad2056dc1e@github.com>

On Wed, 12 Mar 2025 16:25:42 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.
>> 
>> [apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html
>> 
>> https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79
>> 
>> I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).
>> 
>> The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.
>> 
>> The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.
>> 
>> I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.
>
> 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 three commits:
> 
>  - Merge branch 'master' into JDK-8350920
>  - Add svg files
>  - 8350920: Allow inherited member summaries to be viewed inline

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java line 234:

> 232:             // Omit TOC entries for inherited members unless there's a substantial number of own members.
> 233:             if (!inheritedTocEntries.isEmpty() && ownMemberCount > 8 && inheritedSummaries > 0) {
> 234:                 writer.tableOfContents.pushNestedList();

We have removed this system for h3 tag support. Can you update this patch?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23967#discussion_r2011221005

From liach at openjdk.org  Tue Mar 25 03:18:09 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 25 Mar 2025 03:18:09 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG
In-Reply-To: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
Message-ID: <AOSxgs2TE4FZ3HBMdYC9psMpy4pEmMMypqvPzzH-xXI=.327ac7b3-e27a-4db4-ada5-1ecb6522c3bc@github.com>

On Mon, 24 Mar 2025 17:08:32 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
> 
> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
> 
> HtmlTree.of(HtmlTag.IMG)
>                         .put(HtmlAttr.SRC, docpath)
>                         .put(HtmlAttr.ALT, alt)
> 
> 
> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
> 
> No tests are required as part of this change.
> 
> TIA

src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTree.java line 1163:

> 1161:      * {@return an HTML {@code IMG} element}
> 1162:      */
> 1163: 

Suggestion:

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24204#discussion_r2011223141

From hannesw at openjdk.org  Tue Mar 25 04:35:19 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 25 Mar 2025 04:35:19 GMT
Subject: RFR: 8350920: Allow inherited member summaries to be viewed inline
 [v3]
In-Reply-To: <dX1QjYZMvLqrR9bS1YLuvpWlXWTcCo56grLUDgh59Pg=.f908cdb2-911a-4ca3-b86e-a07d86a92a6e@github.com>
References: <dX1QjYZMvLqrR9bS1YLuvpWlXWTcCo56grLUDgh59Pg=.f908cdb2-911a-4ca3-b86e-a07d86a92a6e@github.com>
Message-ID: <IBNUJ2O_vNs15nYYhxoO8zwjtWX1tR7VZccnaheriAk=.e844a00c-ff9b-40d2-a58f-674f050d0bdc@github.com>

> Please review an enhancement to allow switching between the traditional condensed footnote-style summary and the summary table format for inherited members (types, fields, methods and properties) that are inherited from included types. You can test the feature in [the doc bundle I uploaded][apidocs] or watch the short screencast below.
> 
> [apidocs]: https://cr.openjdk.org/~hannesw/8350920/api.00/java.base/module-summary.html
> 
> https://github.com/user-attachments/assets/0aaa1f8b-c18b-4922-b704-2b2cdc05ca79
> 
> I added two new protected methods to the `AbstractMemberWriter` class, `createInheritedSummaryTable` and `getInheritedSummaryId`. Otherwise this is mostly reusing existing functionality (we already had the feature to display the signature of an inherited method in the context of the current class).
> 
> The writers for non-inheritable members such as constructors or enum constants were simplified a bit by implementing formerly abstract methods in `AbstractMemberWriter` as concrete methods throwing `UnsupportedOperationException` so they don't have to be implemented as empty methods in these writers.
> 
> The UI to switch between member list presentations is implemented in `script.js.template`. If no summary list presentation is available (because the supertype is not part of the documentation bundle) nothing changes in the UI.
> 
> I added a `stripTags()` method to `Content` to return the plain text content with HTML tags stripped that could be used in a few other places. The patch also adds two new vector graphics files called right.svg and down.svg for the right and downwards pointing angle.

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 four commits:

 - Merge branch 'master' into JDK-8350920
 - Merge branch 'master' into JDK-8350920
 - Add svg files
 - 8350920: Allow inherited member summaries to be viewed inline

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

Changes: https://git.openjdk.org/jdk/pull/23967/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=23967&range=02
  Stats: 521 lines in 27 files changed: 409 ins; 55 del; 57 mod
  Patch: https://git.openjdk.org/jdk/pull/23967.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23967/head:pull/23967

PR: https://git.openjdk.org/jdk/pull/23967

From nbenalla at openjdk.org  Tue Mar 25 10:06:18 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Mar 2025 10:06:18 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index
In-Reply-To: <qGVbV67-TTut2nSHNsTOgAk6mCpApWmPVlVvXc14jtg=.9db9180c-c8a8-4510-acb2-aea7249331df@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <sll0q60s47RYYy6pAu83OqcsX1HdWCnJdhCCPrcFdRg=.1303359d-ccc2-426c-8a1d-1012c55cfd77@github.com>
 <xYsoxNiTKhPW-CwCMCGPPnUd9w48FD5lNVNVY29pLwU=.1d72bade-6c2c-4d99-9f86-b518a6015485@github.com>
 <qGVbV67-TTut2nSHNsTOgAk6mCpApWmPVlVvXc14jtg=.9db9180c-c8a8-4510-acb2-aea7249331df@github.com>
Message-ID: <DSZ3Zt7gBdwl46gxq3W7tST4C3SzlnsiwW597HP1BuI=.cdc63154-cf0f-489d-bc6d-aa4719f82f47@github.com>

On Mon, 24 Mar 2025 16:39:02 GMT, Chen Liang <liach at openjdk.org> wrote:

>> I thought about it but that may not be necessary because the other json keys (`l`, `h`, `u`) cannot have whitespace in them.
>> 
>> I'm not opposed to handing whitespace in an `escapeQuotesAndWhitespace` method though.
>
> I think we should have one that escapes spaces and another that fails on spaces to replace the current escapeQuotes.

Apologies. Whitespace is indeed allowed in certain keys, I thought that the Labels would mostly be references (links) but titles and headers are also included in the Index files.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24202#discussion_r2011745669

From hannesw at openjdk.org  Tue Mar 25 10:53:18 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 25 Mar 2025 10:53:18 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index
In-Reply-To: <DSZ3Zt7gBdwl46gxq3W7tST4C3SzlnsiwW597HP1BuI=.cdc63154-cf0f-489d-bc6d-aa4719f82f47@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <sll0q60s47RYYy6pAu83OqcsX1HdWCnJdhCCPrcFdRg=.1303359d-ccc2-426c-8a1d-1012c55cfd77@github.com>
 <xYsoxNiTKhPW-CwCMCGPPnUd9w48FD5lNVNVY29pLwU=.1d72bade-6c2c-4d99-9f86-b518a6015485@github.com>
 <qGVbV67-TTut2nSHNsTOgAk6mCpApWmPVlVvXc14jtg=.9db9180c-c8a8-4510-acb2-aea7249331df@github.com>
 <DSZ3Zt7gBdwl46gxq3W7tST4C3SzlnsiwW597HP1BuI=.cdc63154-cf0f-489d-bc6d-aa4719f82f47@github.com>
Message-ID: <V1uHnTyBs71J6RoHEZx86JcdvRDVTc0HCj58pMfAnuo=.2bbf33d5-a896-439a-add5-9829fb4adb97@github.com>

On Tue, 25 Mar 2025 10:03:01 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> I think we should have one that escapes spaces and another that fails on spaces to replace the current escapeQuotes.
>
> Apologies. Whitespace is indeed allowed in certain keys, I thought that the Labels would mostly be references (links) but titles and headers are also included in the Index files.

One thing I noticed is that we have this kind of `"\\s+"` to `" "` whitespace normalization in other related places, notably in `IndexTaglet.java` and `SpecTaglet.java`. Would it make sense to unify the functionality somewhere there, and do it before passing the strings over to `IndexItem`?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24202#discussion_r2011827432

From nbenalla at openjdk.org  Tue Mar 25 10:58:57 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Mar 2025 10:58:57 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG [v2]
In-Reply-To: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
Message-ID: <tDcGOqKi9sQLl8y9YwRqwC4LF_ftqmDHmx7tqYY8D7w=.8e6ee4f4-7f0a-4efa-83f0-b568add439f4@github.com>

> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
> 
> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
> 
> HtmlTree.of(HtmlTag.IMG)
>                         .put(HtmlAttr.SRC, docpath)
>                         .put(HtmlAttr.ALT, alt)
> 
> 
> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
> 
> No tests are required as part of this change.
> 
> TIA

Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:

  remove empty line

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24204/files
  - new: https://git.openjdk.org/jdk/pull/24204/files/a00aecc8..fe9a7a58

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24204&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24204&range=00-01

  Stats: 1 line in 1 file changed: 0 ins; 1 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/24204.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24204/head:pull/24204

PR: https://git.openjdk.org/jdk/pull/24204

From hannesw at openjdk.org  Tue Mar 25 11:15:13 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 25 Mar 2025 11:15:13 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG [v2]
In-Reply-To: <tDcGOqKi9sQLl8y9YwRqwC4LF_ftqmDHmx7tqYY8D7w=.8e6ee4f4-7f0a-4efa-83f0-b568add439f4@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
 <tDcGOqKi9sQLl8y9YwRqwC4LF_ftqmDHmx7tqYY8D7w=.8e6ee4f4-7f0a-4efa-83f0-b568add439f4@github.com>
Message-ID: <4Nqmu9sT6WXxFDusNPN6W50xL1dVAFF9ypw-GOQR3ng=.daaad9f7-af18-4b8f-ac94-00553cfbf69d@github.com>

On Tue, 25 Mar 2025 10:58:57 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
>> 
>> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
>> 
>> HtmlTree.of(HtmlTag.IMG)
>>                         .put(HtmlAttr.SRC, docpath)
>>                         .put(HtmlAttr.ALT, alt)
>> 
>> 
>> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
>> 
>> No tests are required as part of this change.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   remove empty line

src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlTree.java line 1162:

> 1160:     /**
> 1161:      * {@return an HTML {@code IMG} element}
> 1162:      */

It would be nice to also document/mention `src` and `alt` parameters/atttributes.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24204#discussion_r2011868131

From nbenalla at openjdk.org  Tue Mar 25 11:40:35 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Mar 2025 11:40:35 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index [v2]
In-Reply-To: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
Message-ID: <g4VB59jBTopFrCkYIpBg88pZ-aMg3IZdw6LpQSk5d98=.9586e588-b1c8-4c69-9d92-7bebaf520978@github.com>

> Please review this patch to fix an issue in the `tag-search-index.js` generation.
> 
> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
> 
> TIA

Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:

  move logic of normalizing whitespace to the common utils class

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24202/files
  - new: https://git.openjdk.org/jdk/pull/24202/files/a3ae59fe..3e040204

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24202&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24202&range=00-01

  Stats: 11 lines in 5 files changed: 4 ins; 1 del; 6 mod
  Patch: https://git.openjdk.org/jdk/pull/24202.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24202/head:pull/24202

PR: https://git.openjdk.org/jdk/pull/24202

From nbenalla at openjdk.org  Tue Mar 25 11:40:35 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Mar 2025 11:40:35 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index [v2]
In-Reply-To: <V1uHnTyBs71J6RoHEZx86JcdvRDVTc0HCj58pMfAnuo=.2bbf33d5-a896-439a-add5-9829fb4adb97@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <sll0q60s47RYYy6pAu83OqcsX1HdWCnJdhCCPrcFdRg=.1303359d-ccc2-426c-8a1d-1012c55cfd77@github.com>
 <xYsoxNiTKhPW-CwCMCGPPnUd9w48FD5lNVNVY29pLwU=.1d72bade-6c2c-4d99-9f86-b518a6015485@github.com>
 <qGVbV67-TTut2nSHNsTOgAk6mCpApWmPVlVvXc14jtg=.9db9180c-c8a8-4510-acb2-aea7249331df@github.com>
 <DSZ3Zt7gBdwl46gxq3W7tST4C3SzlnsiwW597HP1BuI=.cdc63154-cf0f-489d-bc6d-aa4719f82f47@github.com>
 <V1uHnTyBs71J6RoHEZx86JcdvRDVTc0HCj58pMfAnuo=.2bbf33d5-a896-439a-add5-9829fb4adb97@github.com>
Message-ID: <-Yrn8Ool93uB6-d3fUNgmwGRWCrlGYl1tq0oiI1mPgg=.b39a397d-259a-40fd-943d-a037e5fb6351@github.com>

On Tue, 25 Mar 2025 10:50:19 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Apologies. Whitespace is indeed allowed in certain keys, I thought that the Labels would mostly be references (links) but titles and headers are also included in the Index files.
>
> One thing I noticed is that we have this kind of `"\\s+"` to `" "` whitespace normalization in other related places, notably in `IndexTaglet.java` and `SpecTaglet.java`. Would it make sense to unify the functionality somewhere there, and do it before passing the strings over to `IndexItem`?

Updated in [3e04020](https://github.com/openjdk/jdk/pull/24202/commits/3e040204520084254fbed5d1e4245d13aa24cf42).
I added a new method in `Utils.java` and replaced most uses of `.replaceAll("\\s+", " ")` with it.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24202#discussion_r2011906511

From nbenalla at openjdk.org  Tue Mar 25 12:21:29 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Mar 2025 12:21:29 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG [v3]
In-Reply-To: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
Message-ID: <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>

> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
> 
> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
> 
> HtmlTree.of(HtmlTag.IMG)
>                         .put(HtmlAttr.SRC, docpath)
>                         .put(HtmlAttr.ALT, alt)
> 
> 
> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
> 
> No tests are required as part of this change.
> 
> TIA

Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:

  feedback: document params of the factory method.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24204/files
  - new: https://git.openjdk.org/jdk/pull/24204/files/fe9a7a58..383a4558

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24204&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24204&range=01-02

  Stats: 3 lines in 1 file changed: 3 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/24204.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24204/head:pull/24204

PR: https://git.openjdk.org/jdk/pull/24204

From liach at openjdk.org  Tue Mar 25 13:32:27 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 25 Mar 2025 13:32:27 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG [v3]
In-Reply-To: <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
 <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>
Message-ID: <mg0iKYv8SJuKFs0Z9xGIGAUHr4PrYRcCrJitVQ97qj4=.a772f870-afaf-40b5-9c54-f9dbdd030ef3@github.com>

On Tue, 25 Mar 2025 12:21:29 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
>> 
>> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
>> 
>> HtmlTree.of(HtmlTag.IMG)
>>                         .put(HtmlAttr.SRC, docpath)
>>                         .put(HtmlAttr.ALT, alt)
>> 
>> 
>> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
>> 
>> No tests are required as part of this change.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   feedback: document params of the factory method.

Marked as reviewed by liach (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/24204#pullrequestreview-2713767601

From hannesw at openjdk.org  Tue Mar 25 14:21:28 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 25 Mar 2025 14:21:28 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index [v2]
In-Reply-To: <g4VB59jBTopFrCkYIpBg88pZ-aMg3IZdw6LpQSk5d98=.9586e588-b1c8-4c69-9d92-7bebaf520978@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <g4VB59jBTopFrCkYIpBg88pZ-aMg3IZdw6LpQSk5d98=.9586e588-b1c8-4c69-9d92-7bebaf520978@github.com>
Message-ID: <anrev23kKt7BZrC495ee52Fl_sEvexSjfmxwGOVeZaY=.6d7432b3-e708-4dce-bdc0-d496884909cf@github.com>

On Tue, 25 Mar 2025 11:40:35 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this patch to fix an issue in the `tag-search-index.js` generation.
>> 
>> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   move logic of normalizing whitespace to the common utils class

Looks good to me. A doc comment on the new utils method would be nice.

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24202#pullrequestreview-2713954463

From jjg at openjdk.org  Tue Mar 25 18:44:16 2025
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 25 Mar 2025 18:44:16 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG [v3]
In-Reply-To: <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
 <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>
Message-ID: <6U1UQernp9rCxb17dUPFZUkLn4i7pUV17A5Oj_M6FBs=.1d578ba6-b944-405c-8f6b-fb852e4bbea9@github.com>

On Tue, 25 Mar 2025 12:21:29 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
>> 
>> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
>> 
>> HtmlTree.of(HtmlTag.IMG)
>>                         .put(HtmlAttr.SRC, docpath)
>>                         .put(HtmlAttr.ALT, alt)
>> 
>> 
>> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
>> 
>> No tests are required as part of this change.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   feedback: document params of the factory method.

Marked as reviewed by jjg (Reviewer).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SnippetTaglet.java line 199:

> 197:                         .add(HtmlTree.IMG(pathToRoot.resolve(DocPaths.RESOURCE_FILES)
> 198:                                         .resolve(DocPaths.CLIPBOARD_SVG),
> 199:                                 copySnippetText))

Not for this PR, but another tiny cleanup would be to add an overload to `DocPaths.resolve` that takes multiple arguments to be applied (resolve'd) sequentially

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

PR Review: https://git.openjdk.org/jdk/pull/24204#pullrequestreview-2714844251
PR Review Comment: https://git.openjdk.org/jdk/pull/24204#discussion_r2012734109

From liach at openjdk.org  Tue Mar 25 19:08:07 2025
From: liach at openjdk.org (Chen Liang)
Date: Tue, 25 Mar 2025 19:08:07 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index [v2]
In-Reply-To: <g4VB59jBTopFrCkYIpBg88pZ-aMg3IZdw6LpQSk5d98=.9586e588-b1c8-4c69-9d92-7bebaf520978@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <g4VB59jBTopFrCkYIpBg88pZ-aMg3IZdw6LpQSk5d98=.9586e588-b1c8-4c69-9d92-7bebaf520978@github.com>
Message-ID: <tjqLnybxHiJGy8ZidD2N2lvU1XqndVwDCrD8sMxoT6o=.f56806df-69ca-42f3-8674-6d8424b8f0a5@github.com>

On Tue, 25 Mar 2025 11:40:35 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this patch to fix an issue in the `tag-search-index.js` generation.
>> 
>> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   move logic of normalizing whitespace to the common utils class

Marked as reviewed by liach (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/24202#pullrequestreview-2714896925

From nbenalla at openjdk.org  Wed Mar 26 12:48:16 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Mar 2025 12:48:16 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG [v3]
In-Reply-To: <6U1UQernp9rCxb17dUPFZUkLn4i7pUV17A5Oj_M6FBs=.1d578ba6-b944-405c-8f6b-fb852e4bbea9@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
 <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>
 <6U1UQernp9rCxb17dUPFZUkLn4i7pUV17A5Oj_M6FBs=.1d578ba6-b944-405c-8f6b-fb852e4bbea9@github.com>
Message-ID: <ZcVlQALmGFHRCYUJ0XmwN0rPMY4UTWg9RGVMcxf1uE8=.42ef63e8-c25e-4e8d-8e41-1f4ee42f1fdf@github.com>

On Tue, 25 Mar 2025 18:39:03 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   feedback: document params of the factory method.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SnippetTaglet.java line 199:
> 
>> 197:                         .add(HtmlTree.IMG(pathToRoot.resolve(DocPaths.RESOURCE_FILES)
>> 198:                                         .resolve(DocPaths.CLIPBOARD_SVG),
>> 199:                                 copySnippetText))
> 
> Not for this PR, but another tiny cleanup would be to add an overload to `DocPaths.resolve` that takes multiple arguments to be applied (resolve'd) sequentially

Thanks Jon, a quick grep shows 9 places where we call `resolve` multiple times in a single statement.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24204#discussion_r2014067199

From nbenalla at openjdk.org  Wed Mar 26 12:48:14 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Mar 2025 12:48:14 GMT
Subject: RFR: 8352740: Introduce new factory method HtmlTree.IMG [v3]
In-Reply-To: <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
 <8wvVHnxFbMSz4a8cH-fuCkvuTYDrO5zIf0a1pCP9o3Q=.300db9f0-00ed-4826-8941-e80ba39ec759@github.com>
Message-ID: <fE43fYqeeg9qH4F5hlgnuM3brVmPB4Dsftu_Q-0P6uU=.d6e6a1d3-a1b7-461f-8646-cb5298ec2270@github.com>

On Tue, 25 Mar 2025 12:21:29 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
>> 
>> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
>> 
>> HtmlTree.of(HtmlTag.IMG)
>>                         .put(HtmlAttr.SRC, docpath)
>>                         .put(HtmlAttr.ALT, alt)
>> 
>> 
>> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
>> 
>> No tests are required as part of this change.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   feedback: document params of the factory method.

Thanks for the review!

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

PR Comment: https://git.openjdk.org/jdk/pull/24204#issuecomment-2754281577

From nbenalla at openjdk.org  Wed Mar 26 12:48:17 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Mar 2025 12:48:17 GMT
Subject: Integrated: 8352740: Introduce new factory method HtmlTree.IMG
In-Reply-To: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
References: <boNQy0MXldg7K8iznkE63Gu4EYnEakFzm7GOSLoRpgE=.59c0d258-c98b-4b3e-8244-f1a897e72af4@github.com>
Message-ID: <GcXimv0TOJQtNNcDfmzPRvJvHDjtbyQXA9YePiYloSc=.c0596363-0e24-4184-a5c1-fc692909669d@github.com>

On Mon, 24 Mar 2025 17:08:32 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this small patch to add a new factory method `HtmlTree IMG(DocPath src, String alt)`, to provide a convenient way to reliably create valid tree nodes.
> 
> Previously, all uses of `HtmlTag.IMG` followed a similar pattern :
> 
> HtmlTree.of(HtmlTag.IMG)
>                         .put(HtmlAttr.SRC, docpath)
>                         .put(HtmlAttr.ALT, alt)
> 
> 
> However, it was easy to forget to add the required "alt" attribute. Those have been replaced by the new factory method.
> 
> No tests are required as part of this change.
> 
> TIA

This pull request has now been integrated.

Changeset: c14bbea9
Author:    Nizar Benalla <nbenalla at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/c14bbea93e6701719b934dbd1711d26a91b50d7d
Stats:     31 lines in 4 files changed: 14 ins; 7 del; 10 mod

8352740: Introduce new factory method HtmlTree.IMG

Reviewed-by: liach, jjg

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

PR: https://git.openjdk.org/jdk/pull/24204

From nbenalla at openjdk.org  Wed Mar 26 13:04:06 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Mar 2025 13:04:06 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index [v3]
In-Reply-To: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
Message-ID: <pSfn0PWtJTdHNOeogju3Gz50yrTO2h158SZ7CS0uHAQ=.c2b1f4b6-f7b5-4eb3-9f2a-1f0ebb1d9ccb@github.com>

> Please review this patch to fix an issue in the `tag-search-index.js` generation.
> 
> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
> 
> TIA

Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:

  feedback: add javadoc to `normalizeWhitespace`

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24202/files
  - new: https://git.openjdk.org/jdk/pull/24202/files/3e040204..6942c9da

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24202&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24202&range=01-02

  Stats: 5 lines in 1 file changed: 5 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/24202.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24202/head:pull/24202

PR: https://git.openjdk.org/jdk/pull/24202

From hannesw at openjdk.org  Wed Mar 26 13:04:07 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Mar 2025 13:04:07 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index [v3]
In-Reply-To: <pSfn0PWtJTdHNOeogju3Gz50yrTO2h158SZ7CS0uHAQ=.c2b1f4b6-f7b5-4eb3-9f2a-1f0ebb1d9ccb@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <pSfn0PWtJTdHNOeogju3Gz50yrTO2h158SZ7CS0uHAQ=.c2b1f4b6-f7b5-4eb3-9f2a-1f0ebb1d9ccb@github.com>
Message-ID: <NRx3QMZ8prXeQpPLGY4uVL6ivUS8QjLZxjQnCiNts_0=.6da0b750-ebee-4255-8735-bdb62973efdd@github.com>

On Wed, 26 Mar 2025 13:00:43 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this patch to fix an issue in the `tag-search-index.js` generation.
>> 
>> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   feedback: add javadoc to `normalizeWhitespace`

Marked as reviewed by hannesw (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/24202#pullrequestreview-2717067178

From nbenalla at openjdk.org  Wed Mar 26 13:04:10 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Mar 2025 13:04:10 GMT
Subject: RFR: 8351332: Line breaks in search tag descriptions corrupt JSON
 search index [v2]
In-Reply-To: <g4VB59jBTopFrCkYIpBg88pZ-aMg3IZdw6LpQSk5d98=.9586e588-b1c8-4c69-9d92-7bebaf520978@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
 <g4VB59jBTopFrCkYIpBg88pZ-aMg3IZdw6LpQSk5d98=.9586e588-b1c8-4c69-9d92-7bebaf520978@github.com>
Message-ID: <HLcMnO-l5YdFdPFtwu_XzLGx2u1FlVVWsT9QhI-LbHc=.cf4e1193-45b7-4f84-ab3f-346ef33adf9b@github.com>

On Tue, 25 Mar 2025 11:40:35 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this patch to fix an issue in the `tag-search-index.js` generation.
>> 
>> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   move logic of normalizing whitespace to the common utils class

I've made a small update to add javadoc to the new method.

Thanks for reviewing, Chen and Hannes.

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

PR Comment: https://git.openjdk.org/jdk/pull/24202#issuecomment-2754308332
PR Comment: https://git.openjdk.org/jdk/pull/24202#issuecomment-2754318069

From nbenalla at openjdk.org  Wed Mar 26 13:04:12 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Mar 2025 13:04:12 GMT
Subject: Integrated: 8351332: Line breaks in search tag descriptions corrupt
 JSON search index
In-Reply-To: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
References: <ORYLY69ibNlZhry2LQ8p3rinvsdPvMViRWccVWfJ38I=.1235ca0d-ee91-4bac-b1e8-349a533f9024@github.com>
Message-ID: <joU-ibHFk6ZgOSNY595nHGW-GjEJMVD0gdht4j8SdCs=.ef897a19-3888-4910-b56b-68e8db048ae7@github.com>

On Mon, 24 Mar 2025 14:41:43 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this patch to fix an issue in the `tag-search-index.js` generation.
> 
> The problem was in the `toJSON()` method of `IndexItem`. When adding the description, it's using `escapeQuotes(description)` which only escapes backslashes and quotes, but doesn't normalize whitespace.
> 
> TIA

This pull request has now been integrated.

Changeset: e2a461bd
Author:    Nizar Benalla <nbenalla at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/e2a461bddeade1666fe15fb17cba8c9f4c5e7dab
Stats:     97 lines in 5 files changed: 92 ins; 0 del; 5 mod

8351332: Line breaks in search tag descriptions corrupt JSON search index

Reviewed-by: hannesw, liach

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

PR: https://git.openjdk.org/jdk/pull/24202