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 A compatibility problem is that if library C wants to link to library A on Java 17 with generic anchors and library B on 23 with erased anchors. Is there a way for Javadoc to generate the correct link to both older versions, such as by detecting which anchor format was used by scanning index.html? A similar problem occured before when Javadoc changed `--` around method parameters to `()`. ------------- PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2024059820
