RFR: JDK-8320458: Improve structural navigation in API documentation [v2]

[Hannes Wallnöfer]

On Tue, 9 Jan 2024 23:12:51 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
>>   
>>   Co-authored-by: Andrey Turbanov <turbanoff at gmail.com>
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/script.js.template line 251:
> 
>> 249:     setTopMargin();
>> 250:     // Make sure current element is visible in breadcrumb navigation on small displays
>> 251:     const subnav = document.querySelector("ol.sub-nav-list");
> 
> This is but one instance of many similar `querySelector` calls that leverage CSS class names and/or HTML ids.
> 
> In the Java code, we used named constants for such names, defined in `HtmlStyle` and `HtmlId`, which allows us to use an IDE to track their usage. But that does not work across the language boundary into code like this. I wonder (just asking) if it is worth manually marking the Java constants in some way to indicate the names are also used in JavaScript code.  As an example, this could be done with an individual compile-time arg-free annotation on each constant that needs to be marked, or a single annotation on (say) the `HtmlStyle` class containing an array of enum values for the relevant constants.

Interesting suggestion! What would the advantages of using annotations be compared to just using comments, which could also contain a description of where/how the constants are used?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1448976721