RFR: JDK-8260388: Listing (sub)packages at package level of API documentation

Hannes Wallnöfer hannesw at openjdk.java.net
Wed Mar 10 16:49:21 UTC 2021


This adds a "Related Packages" table to package summary pages with a list of neighboring tables. The rules for including packages is as follows:

 1. The super package of the current package is included if it exists.
 2. Direct subpackages of the current package are included, but only if their number does not exceed 20, in which case no subpackages are included.
 3. If steps 1 and 2 did not produce more than 5 packages, sibling packages of the current package are included, but only if their number is not greater than 5.

In steps 2. and 3. above, either all or no candidate packages are included. In other words, if the threshold is exceeded none of the candidate packages are included in the list. The cut-off values are arbitrary, but have shown to produce reasonably good results with various codebases.

A few example of API documentation generated with this feature:

http://cr.openjdk.java.net/~hannesw/8260388/api.01/
http://cr.openjdk.java.net/~hannesw/8260388/javafx.01/
http://cr.openjdk.java.net/~hannesw/8260388/tomcat.02/
http://cr.openjdk.java.net/~hannesw/8260388/servlet.01/

This is a first step to introduce the new feature. There may be future enhancements to fine-tune the feature or make it more customizable.

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

Commit messages:
 - JDK-8260388: Listing (sub)packages at package level of API documentation

Changes: https://git.openjdk.java.net/jdk/pull/2917/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=2917&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8260388
  Stats: 246 lines in 7 files changed: 245 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk/pull/2917.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/2917/head:pull/2917

PR: https://git.openjdk.java.net/jdk/pull/2917


More information about the javadoc-dev mailing list