` 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:

 - Adjust copy button opacity
 - Changes:
    - reduce rollover transitions on headings and snippets
    - add background and padding to  elements
    - slightly brighten snippets background

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23678/files
  - new: https://git.openjdk.org/jdk/pull/23678/files/1b6443e3..3deae2b5

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

  Stats: 18 lines in 1 file changed: 8 ins; 3 del; 7 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 Feb 21 15:13:08 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Feb 2025 15:13:08 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v6]
In-Reply-To: 
References: 

Message-ID: <_0tn65UDZkAe2ax9RmCn_L9-YLjSLgn8Fss_0AMKPkk=.4a7ae745-626a-4fa1-89fd-440ece71d853@github.com>

On Fri, 21 Feb 2025 15:09:49 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fix test bug

test/langtools/jdk/javadoc/doclet/ReproducibleSnippet/ReproducibleSnippetTest.java line 76:

> 74:                 "#a",
> 75:                 "One#ab",
> 76:                 "overlap in obj1.ab(a());\n     * {@snippet lang = java:\n       ^");

Why did you revert from using a text block for the whole message?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23328#discussion_r1965653654

From nbenalla at openjdk.org  Fri Feb 21 15:13:08 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 21 Feb 2025 15:13:08 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v6]
In-Reply-To: 
References: 
Message-ID: 

> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
> This patch proposes emitting an error when such cases are encountered.
> 
> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.

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

  fix test bug

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23328/files
  - new: https://git.openjdk.org/jdk/pull/23328/files/53259326..56d1623f

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

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

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

From nbenalla at openjdk.org  Fri Feb 21 15:13:08 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 21 Feb 2025 15:13:08 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v5]
In-Reply-To: 
References: 

Message-ID: 

On Thu, 20 Feb 2025 16:54:33 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   respond to feedback

I didn't realize this earlier but the order of the references in the error message isn't always the same 

nizar-mac! $ cat One.java                                                                                
package p;
public interface One {
    /**
     * {@code One obj1}
     * {@snippet lang = java:
     * // @link substring="ab" target="One#ab" :
     * obj1.ab(a()); // @link substring="a" target="#a"
     *} class comment
     */
    int a();
    void ab(int i);
}% 

nizar-mac! $ /.../javadoc One.java
Loading source file One.java...
.....
One.java:5: error: snippet link tags: One#ab and #a overlap in obj1.ab(a());
     * {@snippet lang = java:
       ^
.....
nizar-mac! $ /.../javadoc One.java
Loading source file One.java...
....
One.java:5: error: snippet link tags: #a and One#ab overlap in obj1.ab(a());
     * {@snippet lang = java:
       ^
.....

I had to update the test slightly

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

PR Comment: https://git.openjdk.org/jdk/pull/23328#issuecomment-2674797755

From hannesw at openjdk.org  Fri Feb 21 15:23:54 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 21 Feb 2025 15:23:54 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v6]
In-Reply-To: 
References: 

Message-ID: 

On Fri, 21 Feb 2025 15:13:08 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fix test bug

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

> 150:                                         linkTarget,
> 151:                                         l.target(),
> 152:                                         content.asCharSequence().toString().trim());

Would have beein interesting to use the error message that takes additional `start`, `pos` and `end` parameters to point to the location of the conflicting link inside the snippet. Worth a try if you're inclined, but not required.
Thanks for renaming the var!

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23328#discussion_r1965665713

From nbenalla at openjdk.org  Fri Feb 21 15:23:55 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Fri, 21 Feb 2025 15:23:55 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v6]
In-Reply-To: 
References: 

Message-ID: 

On Fri, 21 Feb 2025 15:17:04 GMT, Hannes Walln?fer  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   fix test bug
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SnippetTaglet.java line 152:
> 
>> 150:                                         linkTarget,
>> 151:                                         l.target(),
>> 152:                                         content.asCharSequence().toString().trim());
> 
> Would have beein interesting to use the error message that takes additional `start`, `pos` and `end` parameters to point to the location of the conflicting link inside the snippet. Worth a try if you're inclined, but not required.
> Thanks for renaming the var!

Will give it another shot, getting a correct end position wasn't very straightforward

> test/langtools/jdk/javadoc/doclet/ReproducibleSnippet/ReproducibleSnippetTest.java line 76:
> 
>> 74:                 "#a",
>> 75:                 "One#ab",
>> 76:                 "overlap in obj1.ab(a());\n     * {@snippet lang = java:\n       ^");
> 
> Why did you revert from using a text block for the whole message?

The error message changes slightly on every run, since the order is different when we read the references.
IIRC it's due to this https://github.com/openjdk/jdk/blob/dfcd0df60c60cf89dc01682264a573ad39e61a17/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SnippetTaglet.java#L147
I left a comment above showing the difference between two javadoc runs

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23328#discussion_r1965671501
PR Review Comment: https://git.openjdk.org/jdk/pull/23328#discussion_r1965668084

From nbenalla at openjdk.org  Tue Feb 25 13:45:31 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Feb 2025 13:45:31 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v7]
In-Reply-To: 
References: 
Message-ID: 

> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
> This patch proposes emitting an error when such cases are encountered.
> 
> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.

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 nine additional commits since the last revision:

 - Improve error message by pointing to location of links
 - Merge branch 'master' into snippet-non-rep
 - fix test bug
 - respond to feedback
 - Merge remote-tracking branch 'origin/master' into snippet-non-rep
 - Merge remote-tracking branch 'upstream/master' into snippet-non-rep
 - adjusting error message
 - Merge remote-tracking branch 'upstream/master' into snippet-non-rep
 - emit error when encountering ambigious link

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23328/files
  - new: https://git.openjdk.org/jdk/pull/23328/files/56d1623f..9b2107d9

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

  Stats: 4540 lines in 98 files changed: 2060 ins; 2193 del; 287 mod
  Patch: https://git.openjdk.org/jdk/pull/23328.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/23328/head:pull/23328

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

From nbenalla at openjdk.org  Tue Feb 25 13:56:54 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Feb 2025 13:56:54 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v7]
In-Reply-To: 
References: 

Message-ID: 

On Tue, 25 Feb 2025 13:45:31 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> 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 nine additional commits since the last revision:
> 
>  - Improve error message by pointing to location of links
>  - Merge branch 'master' into snippet-non-rep
>  - fix test bug
>  - respond to feedback
>  - Merge remote-tracking branch 'origin/master' into snippet-non-rep
>  - Merge remote-tracking branch 'upstream/master' into snippet-non-rep
>  - adjusting error message
>  - Merge remote-tracking branch 'upstream/master' into snippet-non-rep
>  - emit error when encountering ambigious link

The carret position points to the second link (of the two conflicting links)
Here are some examples, there is some text after the carret but I found it hard to deal with.

nizar-mac! $ cat One.java                                                                
package p;
public interface One {
   int j=0;
    /**
     *
     * {@code One obj1}
     * {@snippet lang = java:
     * // @link substring="ab" target="One#ab" :
     * var temp = obj1.ab(a()); // @link substring="a" target="#a"
     *} class comment
     */
    int a();
    void ab(int i);
}
nizar-mac! $ javadoc -d ./out One.java
Loading source file One.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 25-internal-LTS-2025-02-20-1634195.nizarbenalla...
Building tree for all the packages and classes...
Generating ./out/p/One.html...
One.java:12: warning: no @return
    int a();
        ^
One.java:2: warning: no comment
public interface One {
       ^
One.java:3: warning: no comment
   int j=0;
       ^
One.java:8: error: snippet link tags: One#ab and #a overlap in 
     * // @link substring="ab" target="One#ab" :
                                       ^
   var temp = obj1.ab(a());
One.java:13: warning: no comment
    void ab(int i);
         ^
Generating ./out/p/package-summary.html...
Generating ./out/p/package-tree.html...
Generating ./out/constant-values.html...
Generating ./out/overview-tree.html...
Generating ./out/allclasses-index.html...
Building index for all classes...
Generating ./out/allpackages-index.html...
Generating ./out/index-all.html...
Generating ./out/search.html...
Generating ./out/index.html...
Generating ./out/help-doc.html...
1 error
4 warnings
nizar-mac! $ cat Two.java                                                                

package p;
import java.lang.classfile.CodeBuilder;
import java.lang.classfile.CodeElement;
import java.lang.classfile.CodeModel;
import java.lang.classfile.CodeTransform;
import java.lang.classfile.Label;
import java.lang.classfile.PseudoInstruction;
import java.lang.classfile.attribute.CodeAttribute;

public interface Two {
   int j=0;
    /**
     * {@snippet lang=java :
     * cob.with(lt); // @link substring="with" target="CodeBuilder#with"
     * // @link substring="labelBinding" target="CodeBuilder#labelBinding" :
     * cob.labelBinding(lt.label()); // @link substring="label" target="#label"
     * }
     */
    int a();
    void ab(int i);
}
nizar-mac! $ javadoc -d ./out Two.java
Loading source file Two.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 25-internal-LTS-2025-02-20-1634195.nizarbenalla...
Building tree for all the packages and classes...
Generating ./out/p/Two.html...
Two.java:20: warning: no @return
    int a();
        ^
Two.java:11: warning: no comment
public interface Two {
       ^
Two.java:12: warning: no comment
   int j=0;
       ^
Two.java:16: error: snippet link tags: #label and CodeBuilder#labelBinding overlap in cob.with(lt);
     * // @link substring="labelBinding" target="CodeBuilder#labelBinding" :
                                       ^

  cob.labelBinding(lt.label());
Two.java:21: warning: no comment
    void ab(int i);
         ^
Generating ./out/p/package-summary.html...
Generating ./out/p/package-tree.html...
Generating ./out/constant-values.html...
Generating ./out/overview-tree.html...
Generating ./out/allclasses-index.html...
Building index for all classes...
Generating ./out/allpackages-index.html...
Generating ./out/index-all.html...
Generating ./out/search.html...
Generating ./out/index.html...
Generating ./out/help-doc.html...
The generated documentation contains diagnostic markers for invalid input.
1 error
4 warnings

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

PR Comment: https://git.openjdk.org/jdk/pull/23328#issuecomment-2682056417

From hannesw at openjdk.org  Tue Feb 25 14:25:57 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 25 Feb 2025 14:25:57 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v7]
In-Reply-To: 
References: 

Message-ID: 

On Tue, 25 Feb 2025 13:53:59 GMT, Nizar Benalla  wrote:

> The carret position points to the second link (of the two conflicting links) Here are some examples, there is some text after the carret but I found it hard to deal with.

Yes, if you give the error reporting message a multi-line message it will print the first line, then the source position and caret in the next two lines, and then the rest of the message. 

This is a bit weird, and probably a reason to avoid messages with line breaks. Can you narrow down the code fragment further, maybe to just the place in which the links overlap (i.e. the part that is matched by one of the links)?

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

PR Comment: https://git.openjdk.org/jdk/pull/23328#issuecomment-2682150318

From nbenalla at openjdk.org  Tue Feb 25 17:39:24 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Feb 2025 17:39:24 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v8]
In-Reply-To: 
References: 
Message-ID: 

> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
> This patch proposes emitting an error when such cases are encountered.
> 
> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.

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

  trim error message

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23328/files
  - new: https://git.openjdk.org/jdk/pull/23328/files/9b2107d9..e0d70a41

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

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

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

From nbenalla at openjdk.org  Tue Feb 25 17:45:05 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Tue, 25 Feb 2025 17:45:05 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v8]
In-Reply-To: 
References: 

Message-ID: 

On Tue, 25 Feb 2025 17:39:24 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   trim error message

Thanks for the hint, I trimmed the line where the links overlapped to only include the first line using a regex.
Besides the regex, the code is now simpler.

nizar-mac! $ javadoc -d ./out One.java
Loading source file One.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 25-internal-LTS-2025-02-20-1634195.nizarbenalla...
Building tree for all the packages and classes...
Generating ./out/p/One.html...
One.java:12: warning: no @return
    int a();
        ^
One.java:2: warning: no comment
public interface One {
       ^
One.java:3: warning: no comment
   int j=0;
       ^
One.java:8: error: snippet link tags: One#ab and #a overlap in 
     * // @link substring="ab" target="One#ab" :
                                       ^
One.java:13: warning: no comment
    void ab(int i);
         ^

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

PR Comment: https://git.openjdk.org/jdk/pull/23328#issuecomment-2682826945

From hannesw at openjdk.org  Wed Feb 26 02:38:41 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 02:38:41 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v2]
In-Reply-To: 
References: 
Message-ID: 

> 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:
> 
>  - / to switch focus to the search input
>  - . to switch focus to the sidebar filter input
>  - Esc 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 `` 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:

  Move buttons to hide/show sidebar to the bottom and make them keyboard-accessible

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23777/files
  - new: https://git.openjdk.org/jdk/pull/23777/files/b79dd892..4ee7a658

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

  Stats: 17 lines in 3 files changed: 3 ins; 5 del; 9 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  Wed Feb 26 04:47:07 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 04:47:07 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v3]
In-Reply-To: 
References: 
Message-ID: 

> 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:
> 
>  - / to switch focus to the search input
>  - . to switch focus to the sidebar filter input
>  - Esc 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 `` 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:

  - Use themed focus highlight for TOC entries
  - Move focus back on input when typing on TOC focus

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23777/files
  - new: https://git.openjdk.org/jdk/pull/23777/files/4ee7a658..f1a3c0f4

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

  Stats: 10 lines in 2 files changed: 1 ins; 1 del; 8 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  Wed Feb 26 05:31:36 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 05:31:36 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v4]
In-Reply-To: 
References: 
Message-ID: <0RC-UgavsIBSHUJ-mALn6gOyreNHJCHUBxIu6XHvka8=.a88cbe81-cad1-4c61-84d6-0270611e33ad@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:
> 
>  - / to switch focus to the search input
>  - . to switch focus to the sidebar filter input
>  - Esc 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 `` 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:

  Use focus instead of focus-visible to always show focus

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23777/files
  - new: https://git.openjdk.org/jdk/pull/23777/files/f1a3c0f4..28a07fe1

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

  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  Wed Feb 26 08:31:14 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 08:31:14 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v5]
In-Reply-To: 
References: 
Message-ID: 

> 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:
> 
>  - / to switch focus to the search input
>  - . to switch focus to the sidebar filter input
>  - Esc 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 `` 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:

  better workaround for focus-visible problem on Safari

  (Works in Safari Tech Preview, will work in release soon)

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23777/files
  - new: https://git.openjdk.org/jdk/pull/23777/files/28a07fe1..49b68d42

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

  Stats: 8 lines in 2 files changed: 0 ins; 4 del; 4 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  Wed Feb 26 08:48:59 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 08:48:59 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v8]
In-Reply-To: 
References: 

Message-ID: <2f4s-9GcBiTkdTWMGHboRiAR4CqmEfvkcDE7sv88i8I=.734ba6e7-d345-4822-8dc1-567ec6e74e70@github.com>

On Tue, 25 Feb 2025 17:39:24 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   trim error message

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

> 149:                                 var body = tag.getBody().toString();
> 150:                                 var pos = ((DCSnippet) tag).getStartPosition()
> 151:                                         + Math.max(body.indexOf(linkTarget), body.indexOf(l.target()));

Doing a `String.indexOf` on the snippet body is not a good way to do this. It will often return the wrong result, especially if the link target is a class name. 

Sorry Nizar, I was not aware that we don't have any position information anymore at this point when I suggested to look into this. After reading the code, it seems we'd have to check for this condition earlier in the `snippet.Parser` code in order to get a reliable position within the snippet.

I suggest to for now go back to the previous version that just reports the start of the snippet tag, and maybe file a bug to find a better solution, but I would say it isn't a high priority issue.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23328#discussion_r1971170031

From nbenalla at openjdk.org  Wed Feb 26 15:03:46 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Feb 2025 15:03:46 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v9]
In-Reply-To: 
References: 
Message-ID: <7Xe49sUezMIz94q_7dlVB0iW3aKq58S_46ExVgD5HKg=.41edcc7e-6250-4839-89ff-eaed4e504d99@github.com>

> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
> This patch proposes emitting an error when such cases are encountered.
> 
> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.

Nizar Benalla has updated the pull request incrementally with two additional commits since the last revision:

 - Revert "Improve error message by pointing to location of links"

   This reverts commit 9b2107d90203febd9615e7622816432751c3f9e2.
 - Revert "trim error message"

   This reverts commit e0d70a410a1149efa07f6486334fdcad3e31a3c9.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/23328/files
  - new: https://git.openjdk.org/jdk/pull/23328/files/e0d70a41..a808e2c8

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

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

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

From liach at openjdk.org  Wed Feb 26 15:33:54 2025
From: liach at openjdk.org (Chen Liang)
Date: Wed, 26 Feb 2025 15:33:54 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v9]
In-Reply-To: <7Xe49sUezMIz94q_7dlVB0iW3aKq58S_46ExVgD5HKg=.41edcc7e-6250-4839-89ff-eaed4e504d99@github.com>
References: 
 <7Xe49sUezMIz94q_7dlVB0iW3aKq58S_46ExVgD5HKg=.41edcc7e-6250-4839-89ff-eaed4e504d99@github.com>
Message-ID: <-JieBQ1UC_D__Mqd1YtU9z59vFbKdN1dTsFJTeNdccs=.c067b548-48b6-42ad-8e25-f9279594f754@github.com>

On Wed, 26 Feb 2025 15:03:46 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Revert "Improve error message by pointing to location of links"
>    
>    This reverts commit 9b2107d90203febd9615e7622816432751c3f9e2.
>  - Revert "trim error message"
>    
>    This reverts commit e0d70a410a1149efa07f6486334fdcad3e31a3c9.

The rolled back version looks good. Please wait for @hns to review too.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23328#pullrequestreview-2644943623

From nbenalla at openjdk.org  Wed Feb 26 15:33:56 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Feb 2025 15:33:56 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v8]
In-Reply-To: <2f4s-9GcBiTkdTWMGHboRiAR4CqmEfvkcDE7sv88i8I=.734ba6e7-d345-4822-8dc1-567ec6e74e70@github.com>
References: 

 <2f4s-9GcBiTkdTWMGHboRiAR4CqmEfvkcDE7sv88i8I=.734ba6e7-d345-4822-8dc1-567ec6e74e70@github.com>
Message-ID: <3R6zsGqO9yqIpK7bumnp4RrXprAi6qba0_yufNtsIgY=.640e4378-7baf-492f-bcc8-fee66de95dc5@github.com>

On Wed, 26 Feb 2025 08:46:07 GMT, Hannes Walln?fer  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   trim error message
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SnippetTaglet.java line 151:
> 
>> 149:                                 var body = tag.getBody().toString();
>> 150:                                 var pos = ((DCSnippet) tag).getStartPosition()
>> 151:                                         + Math.max(body.indexOf(linkTarget), body.indexOf(l.target()));
> 
> Doing a `String.indexOf` on the snippet body is not a good way to do this. It will often return the wrong result, especially if the link target is a class name. 
> 
> Sorry Nizar, I was not aware that we don't have any position information anymore at this point when I suggested to look into this. After reading the code, it seems we'd have to check for this condition earlier in the `snippet.Parser` code in order to get a reliable position within the snippet.
> 
> I suggest to for now go back to the previous version that just reports the start of the snippet tag, and maybe file a bug to find a better solution, but I would say it isn't a high priority issue.

I've reverted those changes. If the current error message appears to not be clear enough then I'll revisit it.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/23328#discussion_r1971826323

From hannesw at openjdk.org  Wed Feb 26 15:57:01 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 15:57:01 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v3]
In-Reply-To: 
References: 

Message-ID: 

On Thu, 20 Feb 2025 16:25:33 GMT, Nizar Benalla  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 four additional commits since the last revision:
> 
>  - respond to feedback
>  - Merge branch 'master' into javadoc-usage-message
>  - update test with new usage message
>  - improve javadoc executable message

Nice, the new message is definitely an improvement over the old one.

I assume the other JDK tools also exit with OK with no args?

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

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

From hannesw at openjdk.org  Wed Feb 26 16:01:27 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 16:01:27 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v9]
In-Reply-To: <7Xe49sUezMIz94q_7dlVB0iW3aKq58S_46ExVgD5HKg=.41edcc7e-6250-4839-89ff-eaed4e504d99@github.com>
References: 
 <7Xe49sUezMIz94q_7dlVB0iW3aKq58S_46ExVgD5HKg=.41edcc7e-6250-4839-89ff-eaed4e504d99@github.com>
Message-ID: 

On Wed, 26 Feb 2025 15:03:46 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Revert "Improve error message by pointing to location of links"
>    
>    This reverts commit 9b2107d90203febd9615e7622816432751c3f9e2.
>  - Revert "trim error message"
>    
>    This reverts commit e0d70a410a1149efa07f6486334fdcad3e31a3c9.

Thanks Nizar, looks good to me.

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/23328#pullrequestreview-2645023670

From hannesw at openjdk.org  Wed Feb 26 17:34:53 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 26 Feb 2025 17:34:53 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v3]
In-Reply-To: 
References: 

Message-ID: 

On Thu, 20 Feb 2025 16:25:33 GMT, Nizar Benalla  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 four additional commits since the last revision:
> 
>  - respond to feedback
>  - Merge branch 'master' into javadoc-usage-message
>  - update test with new usage message
>  - improve javadoc executable message

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 560:

> 558:                     showLinesUsingKey("main.usage.short");
> 559:                     showLinesUsingKey("main.for-more-details-see-usage");
> 560:                     return OK;

The currently used exit code is `2`, and the message is written to `stderr`, not `stdout`. I think these things should not be changed.

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

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

From duke at openjdk.org  Wed Feb 26 18:08:54 2025
From: duke at openjdk.org (Mikhail Yankelevich)
Date: Wed, 26 Feb 2025 18:08:54 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v5]
In-Reply-To: 
References: 

Message-ID: <-2wbm8SdYm-82E2SQ2k6HgUFsk2o8-WJZvQ73OsoPaA=.738ff2c9-1eac-47c7-84fd-cbf08a40b79e@github.com>

On Wed, 26 Feb 2025 08:31:14 GMT, Hannes Walln?fer  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:
>> 
>>  - / to switch focus to the search input
>>  - . to switch focus to the sidebar filter input
>>  - Esc 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 `` 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:
> 
>   better workaround for focus-visible problem on Safari
>   
>   (Works in Safari Tech Preview, will work in release soon)

Could you please add the `@bug` number for the tests? I believe it would be warranted here

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

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

From nbenalla at openjdk.org  Wed Feb 26 18:39:54 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Feb 2025 18:39:54 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v3]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 26 Feb 2025 17:32:37 GMT, Hannes Walln?fer  wrote:

>> 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 four additional commits since the last revision:
>> 
>>  - respond to feedback
>>  - Merge branch 'master' into javadoc-usage-message
>>  - update test with new usage message
>>  - improve javadoc executable message
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 560:
> 
>> 558:                     showLinesUsingKey("main.usage.short");
>> 559:                     showLinesUsingKey("main.for-more-details-see-usage");
>> 560:                     return OK;
> 
> The currently used exit code is `2`, and the message is written to `stderr`, not `stdout`. I think these things should not be changed.

`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: an unknown error has occurred
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.

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

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

From nbenalla at openjdk.org  Wed Feb 26 20:19:06 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Feb 2025 20:19:06 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v3]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 26 Feb 2025 18:36:50 GMT, Nizar Benalla  wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 560:
>> 
>>> 558:                     showLinesUsingKey("main.usage.short");
>>> 559:                     showLinesUsingKey("main.for-more-details-see-usage");
>>> 560:                     return OK;
>> 
>> The currently used exit code is `2`, and the message is written to `stderr`, not `stdout`. I think these things should not be changed.
>
> `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: an unknown error has occurred
> 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.

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

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

From nbenalla at openjdk.org  Wed Feb 26 21:29:30 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Wed, 26 Feb 2025 21:29:30 GMT
Subject: RFR: 8350007: Add usage message to the javadoc executable [v4]
In-Reply-To: 
References: 
Message-ID: 

> 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 incrementally with two additional commits since the last revision:

 - update test
 - keep the same return value and write to STDERR

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

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

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

  Stats: 5 lines in 2 files changed: 1 ins; 0 del; 4 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 duke at openjdk.org  Thu Feb 27 09:15:04 2025
From: duke at openjdk.org (Mikhail Yankelevich)
Date: Thu, 27 Feb 2025 09:15:04 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v5]
In-Reply-To: 
References: 

Message-ID: 

On Wed, 26 Feb 2025 08:31:14 GMT, Hannes Walln?fer  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:
>> 
>>  - / to switch focus to the search input
>>  - . to switch focus to the sidebar filter input
>>  - Esc 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 `` 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:
> 
>   better workaround for focus-visible problem on Safari
>   
>   (Works in Safari Tech Preview, will work in release soon)

Could you please add the @bug number for the tests? I believe it would be warranted here

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

Changes requested by myankelev at github.com (no known OpenJDK username).

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

From nbenalla at openjdk.org  Thu Feb 27 14:55:16 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Thu, 27 Feb 2025 14:55:16 GMT
Subject: Integrated: 8346659: SnippetTaglet should report an error if provided
 ambiguous links
In-Reply-To: 
References: 
Message-ID: 

On Tue, 28 Jan 2025 11:23:36 GMT, Nizar Benalla  wrote:

> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
> This patch proposes emitting an error when such cases are encountered.
> 
> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.

This pull request has now been integrated.

Changeset: 8323ddfe
Author:    Nizar Benalla 
URL:       https://git.openjdk.org/jdk/commit/8323ddfe189e8a189176a37746985c2473ebab3b
Stats:     117 lines in 4 files changed: 88 ins; 12 del; 17 mod

8346659: SnippetTaglet should report an error if provided ambiguous links

Reviewed-by: hannesw, liach

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

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

From nbenalla at openjdk.org  Thu Feb 27 14:55:15 2025
From: nbenalla at openjdk.org (Nizar Benalla)
Date: Thu, 27 Feb 2025 14:55:15 GMT
Subject: RFR: 8346659: SnippetTaglet should report an error if provided
 ambiguous links [v9]
In-Reply-To: <7Xe49sUezMIz94q_7dlVB0iW3aKq58S_46ExVgD5HKg=.41edcc7e-6250-4839-89ff-eaed4e504d99@github.com>
References: 
 <7Xe49sUezMIz94q_7dlVB0iW3aKq58S_46ExVgD5HKg=.41edcc7e-6250-4839-89ff-eaed4e504d99@github.com>
Message-ID: 

On Wed, 26 Feb 2025 15:03:46 GMT, Nizar Benalla  wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Revert "Improve error message by pointing to location of links"
>    
>    This reverts commit 9b2107d90203febd9615e7622816432751c3f9e2.
>  - Revert "trim error message"
>    
>    This reverts commit e0d70a410a1149efa07f6486334fdcad3e31a3c9.

Thanks for the reviews, glad we fixed this.

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

PR Comment: https://git.openjdk.org/jdk/pull/23328#issuecomment-2688191986

From hannesw at openjdk.org  Fri Feb 28 14:53:09 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 28 Feb 2025 14:53:09 GMT
Subject: RFR: 8344301: Refine stylesheet for API docs [v3]
In-Reply-To: 
References: 
Message-ID: 

> 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 `` 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:

  Changes:

   - Only use orange color for highlighted tab in a group,
     blue tab for single caption
   - Match design of inherited member header to other member
     summary captions
   - Improve sidebar highlight
   - Slight increase of remaining font sizes and line heights
   - Slight increase of subnavigation header and search box height
   - Deburr some sharp corners

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

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

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

  Stats: 144 lines in 4 files changed: 37 ins; 65 del; 42 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 Feb 28 15:13:07 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 28 Feb 2025 15:13:07 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: 
References: 
Message-ID: 

> 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:
> 
>  - / to switch focus to the search input
>  - . to switch focus to the sidebar filter input
>  - Esc 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 `` 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

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

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

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

  Stats: 4 lines in 4 files changed: 0 ins; 0 del; 4 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 Feb 28 15:16:52 2025
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 28 Feb 2025 15:16:52 GMT
Subject: RFR: 8350638: Make keyboard navigation more usable in API docs
 [v6]
In-Reply-To: 
References: 

Message-ID: 

On Fri, 28 Feb 2025 15:13:07 GMT, Hannes Walln?fer  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:
>> 
>>  - / to switch focus to the search input
>>  - . to switch focus to the sidebar filter input
>>  - Esc 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 `` 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

Thanks for the suggestion, I added the bug id to the tests that seemed most on topic.

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

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