RFR: 8323698: Class use page does not include extends/implements type arguments [v5]

[Pavel Rappo]

On Thu, 22 Feb 2024 04:53:20 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Currently in the javadoc tool, the generated class use page does not track the occurrences of a class in the type arguments of the extends or implements list, where they can appear. (See more details on the JBS issue) For example:
>> 
>> public class One {}
>> 
>> 
>> import java.util.*;
>> public class Two extends ArrayList<One> implements Comparator<One> {
>> }
>> 
>> 
>> This patch proposes to add new 2 usage categories, "Classes that extend types with arguments of type" and "Classes that implement types with arguments of type" to describe the missing usage scenarios.
>> 
>> A preview of the new use page with the 2 new categories, generated based on the example above, can be found here: https://cr.openjdk.org/~liach/8323698-javadocuse/doc/class-use/One.html
>
> Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains eight additional commits since the last revision:
> 
>  - Distinguish subinterfaces, use clearer terms
>  - Merge branch 'master' of https://github.com/openjdk/jdk into feature/jd-use-super-typearg
>  - Review changes
>  - Merge branch 'master' of https://github.com/openjdk/jdk into feature/jd-use-super-typearg
>  - Fix tests
>  - Improve localization
>  - Merge branch 'master' of https://github.com/openjdk/jdk into feature/jd-use-super-typearg
>  - Use page to check extends/implements type arguments

Mostly looks good.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 286:

> 284:     subclasses with parameters of type A.  \
> 285:     You can access this page by first going to the package, class or interface, then clicking on \
> 286:     the USE link in the navigation bar.

Thanks for catching this! Consider this wording:


doclet.help.use.body=\
    Each documented package, class or interface has its own Use page, which lists \
    packages, classes, interfaces, methods, constructors and fields that use any \
    part of that package, class or interface. Given a class or interface A, its \
    Use page includes subclasses or subinterfaces of A, fields declared as A, \
    methods that return A, methods and constructors with parameters of type A, \
    and subclasses or subinterfaces with parameters of type A. You can access \
    this page by first going to the package, class or interface, then clicking \
    on the USE link in the navigation bar.


There are a couple of other issues there which should be fixed in a separate PR.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java line 98:

> 96: 
> 97:     /**
> 98:      * Mapping of TypeElements to list of TypeElements which uses this class in a superclass type parameter

Suggestion:

     * Mapping of TypeElements to list of TypeElements which use this class in a superclass type parameter.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java line 103:

> 101: 
> 102:     /**
> 103:      * Mapping of TypeElements to list of TypeElements which uses this class in a superclass type parameter

Suggestion:

     * Mapping of TypeElements to list of TypeElements which use this class in a superclass type parameter.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ClassUseMapper.java line 108:

> 106: 
> 107:     /**
> 108:      * Mapping of TypeElements to list of TypeElements which uses this interface in a superinterface type parameter

Suggestion:

     * Mapping of TypeElements to list of TypeElements which use this interface in a superinterface type parameter.

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17414#pullrequestreview-1895852396
PR Review Comment: https://git.openjdk.org/jdk/pull/17414#discussion_r1499240047
PR Review Comment: https://git.openjdk.org/jdk/pull/17414#discussion_r1499243536
PR Review Comment: https://git.openjdk.org/jdk/pull/17414#discussion_r1499244013
PR Review Comment: https://git.openjdk.org/jdk/pull/17414#discussion_r1499244219