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

[Jonathan Gibbons]

On Wed, 24 Mar 2021 16:14:11 GMT, Hannes Wallnöfer <hannesw at openjdk.org> 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.
>
> Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   JDK-8260388: Add check for configuration.showModules

Definitely better with the new column for the linked module name.

This is OK as is, but I think it would be better to have the module column first, before the package column.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java line 169:

> 167:         boolean showModules = configuration.showModules && hasRelatedPackagesInOtherModules(relatedPackages);
> 168:         TableHeader tableHeader= showModules
> 169:                 ? new TableHeader(contents.packageLabel, contents.moduleLabel, contents.descriptionLabel)

This is OK, but I think it would be better if the module column came first.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java line 251:

> 249:                                   TableHeader tableHeader, Content summaryContentTree,
> 250:                                   boolean showModules) {
> 251:         if(!packages.isEmpty()) {

whitespace after `if`

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java line 282:

> 280:                 }
> 281:                 if (showModules) {
> 282:                     table.addRow(packageLink, moduleLink, description);

This looks like the companion row to the header entry, to put the module column first.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 448:

> 446:      * information without any particular style.
> 447:      */
> 448:     colExtra,

The `extra` in the same seems irrelevant. How about `colPlain`, to indicate it is a column with no additional style.

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

Marked as reviewed by jjg (Reviewer).

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