On Mon, 19 Apr 2021 09:45:27 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
>> This adds a feature to add sub-navigation links to the package summary page, >> but ended up more like a refactoring of the code to generate sub-navigation >> links. The reason for this is that generation of these links was highly >> idiosyncratic. Every writer class that wanted to create sub-nav links >> deposited something of itself in the `Navigation` instance which was then >> responsible for generating these links. The new code introduces a >> `Navigation.SubNavLinks` interface that allows writers to provide a list of >> links into their page content. >> >> As for the new feature in the package summary page itself, I chose an >> approach that is a bit different from the one we use for other types of >> pages. Instead of displaying the inactive label instead of the link when a >> section is not present on the page, only the active links are displayed. The >> reason for this is that the package summary page contains so many potential >> summary tables that the sub-nav area gets quite crowded if they are all >> shown. Just showing the actually present pieces looked better to me. >> >> Like in other sub-nav sections, the link labels sometimes use abbreviated >> terms such as "RELATED" instead of "RELATED PACKAGES" and "ENUMS" instead of >> "ENUM CLASSES". The full list of potential package sub-nav links is as >> follows: >> >> Package: Description | Related | Interfaces | Classes | Enums | Records >> | Exceptions | Errors | Annotations >> >> An important implementation note is that I moved the code to compute package >> summary contents from `PackageSummaryBuilder` to `PackageWriterImpl`. The >> reason for this is that the contents are required to determine which links >> to create, and I didn't want to re-compute this information that was >> previously computed on the fly in the builder class. The various summary >> items are now stored in collection fields in the writer class. >> >> I have tried to add all the new properties and constants in a sensible >> place, which usually means alphabetic order within the sub-group of related >> entries. >> >> I chose to keep the markup structure of the package summary page mostly >> unchanged, adding only `id` attributes to the existing `<li>` elements for >> each summary table. I decided against adding `class` attributes as well as >> it seems very unlikely to me that somebody would want to apply different >> styles to the various summary tables. Even without them, it could be done >> using the `id`s. > > Hannes Wallnöfer has updated the pull request incrementally with one > additional commit since the last revision: > > JDK-8263507: Update JBS summary I opted for doing the summary table merge within this same PR. I couldn't find an existing JBS issue for it, and splitting the work into two changesets and reverse their order seemed like a non-trivial amount of work. I have updated the JBS summary to "Improve structure of package summary pages" to reflect the broader scope. ------------- PR: https://git.openjdk.java.net/jdk/pull/3413
