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 >>> >
