RFR: 8352511: Show additional level of headings in table of contents [v2]

[Chen Liang]

On Fri, 21 Mar 2025 03:12:39 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Please review a patch to show an additional level of headings in the table of contents for module, package and class descriptions. Previously only `<h2>` headings were shown in the table of contents, now we also show `<h3>` level headings.
>> 
>> The `TableOfContents` class no longer provides `pushNestedList`/`popNestedList` methods that require us to manually manage nesting level. Instead, the method to add a TOC entry gets an additional `level` parameter with an enum type to specify the nesting level (`FIRST`, `SECOND`, `THIRD`). The class will then configure the list to the desired nesting level before adding the entry. Of course this works with both tradidtional and Markdown doc comments and has tests for both.
>> 
>> There are not too many API elements in JDK that use `<h3>` level headings, but those that do benefit a lot from this change. A few examples:
>> 
>>  - [package java.util.stream](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/util/stream/package-summary.html)
>>  - [package java.lang.classfile](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/classfile/package-summary.html)
>>  - [package java.lang.invoke](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/invoke/package-summary.html)
>>  - [package java.lang.module](https://cr.openjdk.org/~hannesw/8352511/api.00/java.base/java/lang/module/package-summary.html)
>> 
>> This PR depends on #24083 not for technical reasons but because that PR fixes the rendering of the third level of TOC entries.
>
> Hannes Wallnöfer has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Update copyright headers
>  - Update ListBuilder

Looks good. Since the removal of old push/pop will cause compile errors, I assume you have updated all legacy sites.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/24137#pullrequestreview-2704760704