On Wed, 27 Mar 2024 21:56:48 GMT, Chen Liang <li...@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 `()`. @liach, after a chat to Jon elsewhere, I'm unarchiving my previous solution, which solved another issue, but might also help with the issue you raised. Stay tuned. ------------- PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2025917914
