On Wed, 3 Jan 2024 12:36:15 GMT, Hannes Wallnöfer <hann...@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 <turban...@gmail.com> test/langtools/jdk/javadoc/doclet/testAnchorNames/TestAnchorNames.java line 71: > 69: <section class="nested-class-summary" > id="nested-class-summary"> > 70: <h2>Nested Class Summary</h2>""", > 71: "<a href=\"#nested-class-summary\" tabindex=\"0\">", TIL: tabindex ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1445504581
