JDK-8260388: Listing (sub)packages at package level of API documentation #2917
Conversation
|
|
Webrevs
|
|
Mailing list message from Daniel Fuchs on javadoc-dev: Hi Hannes, I wonder if it's a good idea (or not) to show "related" packages For instance - if you click on java.base, then on java.net, you see - java.net.spi (which is in java.base) I wonder if this is going to cause confusion. Similarly - jf clicking on module java.net.http, and then on Otherwise - I agree that for other packages - like java.lang - it 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: |
|
Mailing list message from Hannes Wallnoefer on javadoc-dev: Hi Daniel, Thanks for the feedback (and the review of the java.net.URI change). I agree that the value of this feature varies depending on the code base, since it is all based on package naming. However, I think the module spanning aspect is actually a good thing in most cases, as it complements the exising hierarchichal structure of documentation. For example, in the case of the java.net and java.net.http packages, it could be quite useful for somebody looking for the java.net.URL* classes to be reminded that there is actually a fully featured HTTP client as well, should they need one. There are other cross-module links that could be useful, such as the inclusion of java.util.logging and java.util.prefs in the java.util package summary. I admit the link between java.net.http and java.net.spi is useless, but I don?t think it?s that confusing either. IMO the feature has a positive net benefit. But of course it can and should be improved further based on feedback we get. Hannes
|
|
Mailing list message from Daniel Fuchs on javadoc-dev: Hi Hannes, I am a bit conflicted about this. I agree with you that the link from java.net to java.net.http can I guess my main gripe is the fact that when the related package is How about changing that? Something like: Package java.net Related Packages + java.net.spi + java.net.http in module java.net.http best regards, -- daniel On 11/03/2021 09:14, Hannes Wallnoefer wrote:
|
|
Mailing list message from Hannes Wallnoefer on javadoc-dev: That is a very good idea to make users aware of the cross-module link. I?ll give it a try and see how it works. Thanks Daniel! Hannes
|
|
Mailing list message from Hannes Wallnoefer on javadoc-dev: Daniel, I uploaded documentation with the cross-module link indication you suggested: http://cr.openjdk.java.net/~hannesw/8260388/api.02/ I?m not qute convinced, curious to hear what you and others think. Hannes
|
|
Mailing list message from Daniel Fuchs on javadoc-dev: Hi Hannes, I think I like it better - could be even more useful if the You're not planning to introduce any javadoc tag to best regards, -- daniel On 11/03/2021 13:59, Hannes Wallnoefer wrote:
|
All OK; some suggestions for future work/cleanup/improvement
| // Maximum number of subpackages and sibling packages to list in related packages table | ||
| private final static int MAX_SUBPACKAGES = 20; | ||
| private final static int MAX_SIBLING_PACKAGES = 5; | ||
|
|
There was a problem hiding this comment.
For future work, move these to a config file.
Short-term "workaround" suggestions still for a separate RFR: annotate these and similar declarations with an internal source-retention annotation of @Configuration
|
@hns This change now passes all automated pre-integration checks. After integration, the commit message for the final commit will be: You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed. At the time when this comment was updated there had been 44 new commits pushed to the
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.
|
|
I have added a change to this PR to add a "Module" column to the related packages table if any of the packages is in a different module. Example output for the JDK libraries is available here ( http://cr.openjdk.java.net/~hannesw/8260388/api.03/ Implementation note: I added a HtmlStyle.colExtra CSS style because existing column classes either had unwanted rules (such as displaying links in bold font) or didn't fit for other reasons. |
|
Mailing list message from Daniel Fuchs on javadoc-dev: On 24/03/2021 15:04, Hannes Walln?fer wrote:
I like it! :-) cheers, -- daniel |
|
Mailing list message from Jonathan Gibbons on javadoc-dev: I like it except that I was expecting the module name (column) to Is there a strong reason to have the module name column appear second? -- Jon On 3/24/21 8:04 AM, Hannes Walln?fer wrote: |
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.
| public void addRelatedPackagesSummary(List<PackageElement> relatedPackages, Content summaryContentTree) { | ||
| boolean showModules = configuration.showModules && hasRelatedPackagesInOtherModules(relatedPackages); | ||
| TableHeader tableHeader= showModules | ||
| ? new TableHeader(contents.packageLabel, contents.moduleLabel, contents.descriptionLabel) |
There was a problem hiding this comment.
This is OK, but I think it would be better if the module column came first.
There was a problem hiding this comment.
I tried it out and was very surprised to find I agree with you. I'm changing the order in a new commit.
| public void addPackageSummary(List<PackageElement> packages, Content label, | ||
| TableHeader tableHeader, Content summaryContentTree, | ||
| boolean showModules) { | ||
| if(!packages.isEmpty()) { |
There was a problem hiding this comment.
whitespace after if
| addSummaryComment(pkg, description); | ||
| } | ||
| if (showModules) { | ||
| table.addRow(packageLink, moduleLink, description); |
There was a problem hiding this comment.
This looks like the companion row to the header entry, to put the module column first.
| * The class of the cells in a table column used to display additional | ||
| * information without any particular style. | ||
| */ | ||
| colExtra, |
There was a problem hiding this comment.
The extra in the same seems irrelevant. How about colPlain, to indicate it is a column with no additional style.
There was a problem hiding this comment.
I was considering colPlain, but dismissed it because I thought we or somebody else might actually add styles to it at some point. But I'll take the risk of future cognitive dissonance and go with colPlain.
|
/integrate |
openjdk
bot
added
integrated
|
@hns Since your change was applied there have been 44 commits pushed to the
Your commit was automatically rebased without conflicts. Pushed as commit a9d287a. |
This adds a "Related Packages" table to package summary pages with a list of neighboring tables. The rules for including packages is as follows:
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.
Progress
Issue
Reviewers
Download
To checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/2917/head:pull/2917$ git checkout pull/2917To update a local copy of the PR:
$ git checkout pull/2917$ git pull https://git.openjdk.java.net/jdk pull/2917/head