Hi Hannes,
I wonder if it's a good idea (or not) to show "related" packages
that come from other modules.
For instance - if you click on java.base, then on java.net, you see
2 related packages:
- java.net.spi (which is in java.base)
- java.net.http - which is in another module (java.net.http) - but
this information is absent from the table.
I wonder if this is going to cause confusion.
Similarly - jf clicking on module java.net.http, and then on
package java.net.http, you see java.net and java.net.spi as
related package. But the spi from java.net.spi is not used
in any way by java.net.http. So this is a bit more questionable
whether this reference is useful.
Otherwise - I agree that for other packages - like java.lang - it
does look good.
Maybe the list should limit itself to subpackages in the same module?
best regards,
-- daniel
On 10/03/2021 16:49, Hannes Wallnöfer wrote:
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
