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

[Hannes Wallnoefer]

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.wallnoefer at 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.fuchs at 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.fuchs at 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
>>>> 
>> 
>