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
-------------
Commit messages:
- Update copyright years
- Add more tests
- Add test
- Fix links from index and TOC
- Fix index order
- Fix summary table
Changes: https://git.openjdk.org/jdk/pull/18519/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18519&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8325088
Stats: 554 lines in 17 files changed: 420 ins; 61 del; 73 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
