On Mon, 11 Dec 2023 16:36:09 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 list order is important... src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java line 47: > 45: import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; > 46: import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode; > 47: import jdk.javadoc.internal.doclets.formats.html.markup.Text; Quibble: order of imports? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java line 425: > 423: List<Content> subnavLinks = new ArrayList<>(); > 424: if (configuration.showModules) { > 425: ModuleElement mdle = > configuration.docEnv.getElementUtils().getModuleOf(typeElement); It's more common to use `utils.elementUtils` than the expression `configuration.docEnv.getElementUtils()` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Headings.java line 125: > 123: static final TagName SUMMARY_HEADING = TagName.H2; > 124: } > 125: Yay! src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/ListBuilder.java line 41: > 39: * list. Lists can be added to and removed from the stack using the > {@code pushNested} > 40: * and {@code popNested} methods. > 41: */ Nice! ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1425741244 PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1425745958 PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1425755714 PR Review Comment: https://git.openjdk.org/jdk/pull/17062#discussion_r1425756738