RFR: 8325088: Overloads that differ in type parameters may be lost [v6]

[Pavel Rappo]

> Creating a link to a constructor or a method or comparing constructors or methods __does not__ factor in type parameters. When constructors or methods are overloaded and differ only in type parameters -- a situation which is absent in JDK API, but present elsewhere -- that causes significant defects, such as:
> 
>   - missing entries in summary tables, lists and indexes,
>   - duplicating links in the table of contents.
> 
> This PR fixes those defects, and the fix is two-fold. Firstly, we update comparators to consider type parameters. That takes care of missing constructors and methods. Secondly, we update id (anchor) and link generation to always use the "erased" notation. That takes care of duplicating links.
> 
> What's the "erased" notation? Suppose we have the following method:
> 
>     <T extends String> T m(T arg)
> 
> The current notation refers to it as `m(T)`. That works fine until there's no other method, such as
> 
>     <T> T m(T arg)
> 
> In which case, the current notation will produce a collision: `m(T)`. By contrast, the erased notation for those two methods is `m(java.lang.String)` and `m(java.lang.Object)` respectively. No collision.
> 
> While longer, I believe that the erased notation is collision-proof. Why? Because [JLS 8.4.2][] says that "it is a compile-time error to declare two methods with override-equivalent signatures in a class". Which means that for any two constructors or methods the erasure of their signatures must differ, or else it won't compile.
> 
> The change is pretty straightforward, except for some test fallout that required attention.
> 
> [JLS 8.4.2]: https://docs.oracle.com/javase/specs/jls/se22/html/jls-8.html#jls-8.4.2

Pavel Rappo 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 20 additional commits since the last revision:

 - Merge branch 'master' into 8325088
 - Update copyright years
   
   Note: any commit hashes below might be outdated due to subsequent
   history rewriting (e.g. git rebase).
   
    + update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java due to 0f33a6477e0
 - Clean up
 - Use a list of alternative ids
 - Cache forMember
 - Clarify some comments
 - Do not handle @interface methods specially
 - Nix forMember used by AnnotationTypeMemberWriter
 - Respond to feedback
 - Merge branch 'master' into 8325088
 - ... and 10 more: https://git.openjdk.org/jdk/compare/60305b37...ffe4078d

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18519/files
  - new: https://git.openjdk.org/jdk/pull/18519/files/4dee61b7..ffe4078d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=18519&range=05
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18519&range=04-05

  Stats: 12589 lines in 348 files changed: 4959 ins; 5873 del; 1757 mod
  Patch: https://git.openjdk.org/jdk/pull/18519.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18519/head:pull/18519

PR: https://git.openjdk.org/jdk/pull/18519