> 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 list order is important...
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> ------------- Changes: - all: https://git.openjdk.org/jdk/pull/17062/files - new: https://git.openjdk.org/jdk/pull/17062/files/40f6486d..4c6f4223 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=17062&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17062&range=00-01 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/17062.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/17062/head:pull/17062 PR: https://git.openjdk.org/jdk/pull/17062