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 > Am 11.03.2021 um 12:07 schrieb Hannes Wallnoefer > <hannes.wallnoe...@oracle.com>: > > 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 > >> Am 11.03.2021 um 10:50 schrieb Daniel Fuchs <daniel.fu...@oracle.com>: >> >> Hi Hannes, >> >> I am a bit conflicted about this. >> >> I agree with you that the link from java.net to java.net.http can >> be useful. >> >> I guess my main gripe is the fact that when the related package is >> not in the same module this is not apparent. >> >> How about changing that? >> I mean - when the related package is in an other module could >> this information be recorded in the table? >> >> 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: >>> 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 >>>> Am 10.03.2021 um 18:18 schrieb Daniel Fuchs <daniel.fu...@oracle.com>: >>>> >>>> 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 >>>> >> >
