On Wed, 27 Mar 2024 17:19:35 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
> 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 Let me note that it's a separate issue to (i) disambiguate link _labels_ in index, search, and TOC, and (ii) to ensure that `@link`, `@see`, etc. are capable of processing the erased notation. ------------- PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2023377778
