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/testNavigation/TestNavigation.java line 58: > 56: @Test > 57: public void testOverview(Path ignore) { > 58: javadoc("-d", "out-overview", Generally, I would recommend renaming `Path ignore` to `Path base` and then generating a filename for use in the `javadoc` call, such as `base.resolve("api").toString()`. This helps guarantee the files for each test case are isolated. test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java line 175: > 173: }"""); > 174: > 175: javadoc("-d", "out-navlinks", See preceding comment. I would recommend using the equivalent of `base.resolve("api:).toString()` here. test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java line 214: > 212: <li><a href="#method-summary" tabindex="0">Method > Summary</a></li> > 213: <li><a href="#constructor-detail" > tabindex="0">Constructor Details</a> > 214: <ol class="toc-list"> General comment, not specific to this instance: I like that we cleaned up HTML id names in recent releases. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1448122752 PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1448123312 PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1448126307