Hannes,
Reading your email, and the comments about the number of tables, reminds
me of the suggestion to merge most of the tables (all those for
different kinds of classes and interfaces) into a single tabbed table,
as is now becoming more prevalent through the rest of the output. This
would simplify the package summary page to two(?) tables, one for
"related packages" (no tabs) and one for "classes and interfaces" (with
tabs for the kind)
This is not meant to invalidate the general work you have done to
improve the code in Navigation, but it might simplify the use of the new
code. The package sub-nav would have 3(?) entries, for Description,
Related, Classes-and-Interfaces
-- Jon
On 4/9/21 7:29 AM, Hannes Wallnöfer 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.
-------------
Commit messages:
- JDK-8263507: Simplify list creation
- JDK-8263507: Rename some methods and add some docs
- JDK-8263507: Add links to page sections in sub-navigation of package
summaries
Changes: https://git.openjdk.java.net/jdk/pull/3413/files
Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3413&range=00
Issue: https://bugs.openjdk.java.net/browse/JDK-8263507
Stats: 1106 lines in 24 files changed: 525 ins; 480 del; 101 mod
Patch: https://git.openjdk.java.net/jdk/pull/3413.diff
Fetch: git fetch https://git.openjdk.java.net/jdk pull/3413/head:pull/3413
PR: https://git.openjdk.java.net/jdk/pull/3413
