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

[Jonathan Gibbons]

On Wed, 3 Jan 2024 12:36:15 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> This is a rather big change to update the structural navigation in API documentation generated by JavaDoc. It adds a table of contents for the current page to module, package, and class documentation, and replaces the old sub-navigation bar with a breadcrumb-style links in those pages. The table of contents is displayed as sidebar on wide/desktop displays and integrated into the collapsible menu for narrow/mobile displays. The generated docs can be browsed here:
>> 
>> https://cr.openjdk.org/~hannesw/8320458/api.00/
>> 
>> This change includes improvements in `stylesheet.css` and `script.js` that are not strictly related to the navigation changes, but happened as a consequence of the necessary restructuring. All these are described together with the more on-topic changes in the list below.
>> 
>>  - The table of contents is composed as the respective writers generate the pages. For this purpose, `HtmlDocletWriter` has a new `tocBuilder` field of new type `ListBuilder`. If the field is not `null` it is used to build the table of contents as the page is built using either one of the  new`HtmlDocletWriter.addToTableOfContents` methods or the `ListBuilder` directly.
>>  - Once the TOC is built, `HtmlDocletWriter.getSideBar` is used to generate the markup for the sidebar and it is added to the page via the `BodyContents.setSideContent` method.
>>  - Both existing navigation bars (top and sub-navigation) get an additional `<div>` container with CSS class `nav-content` that uses a flex layout for its content. This also handles vertical positioning, so the old workaround for vertical of the language version label in `Docs.gmk` is not necessary anymore.
>>  - Apart from modules, packages, and classes, other pages that were converted to obtain a table of contents are the "Constant Field Values" page and the Help page. 
>>  - Originally, I used the `<aside>` element for the sidebar, but I learned that this was the wrong element as it is meant for content that is not strictly related to the main content of the page. The prevailing notion seems to be that a table of contents is a navigation element and therefore should use the `<nav>` element, so I used that for the TOC sidebar. The same applies for the breadcrumbs sub-navigation, so I left the header `<nav>` element wrapped around both top and sub-navigation.
>>  - For the new lists in TOC and breadcrumbs I used ordered list elements `<ol>` instead of unordered `<ul>` we use everywhere else, as that is what should be used when...
>
> 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>

test/langtools/jdk/javadoc/doclet/testCopyFiles/TestCopyFiles.java line 60:

> 58:                 // check top navbar
> 59:                 """
> 60:                     <a href="../package-tree.html">Tree</a>""",

What is the significance of this filename change?

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

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