On Tue, 4 Jan 2022 17:19:44 GMT, Jan Lahoda <jlah...@openjdk.org> wrote:
> Currently, when javac encounters a javadoc reference, like `@see > PrintStream#println(int)`, will first try to find a method `println` in > `PrintStream` using subtyping on the argument types, which may find another > overload of the method with an argument that is a subtype of `int` - like > `println(double)`. Consequently, the link in the javadoc may be to a wrong > method. > > In this patch, the proposal is to use the subtype search only as a backup > option, using the existing check based on `isSameType` first, and only doing > an inexact match using subtyping if the more exact match fails to find a > method. This fallback should help possible existing broken references to > still work as before, while the preferred use of the more exact match should > select the correct method in usual correct cases. > > This patch fixes some instances of incorrect references in the JDK's javadoc, > a diff of the generated javadocs for the JDK mainline is here: > http://cr.openjdk.java.net/~jlahoda/8278373/JDK-8278373.diff Generally good; I think this is the right fix in the current situation and for potential back porting. It provides improved but compatible behavior. The API diffs were an unexpected "bonus", if that is the right word. It's better to know about and fix issues than to not know about them. I've spot checked a few of them and all seem reasonable. The fix is especially obvious when the link and the clear-text are different and meant to be the same. The one thing I would suggest is that because a lot of the api diffs are related to "subtyping" between primitive types, we might want to add some test cases for that into the test as well. Here is a random example of the kind of diff I'm talking about: ``` - as if by calling <a href="../java.base/java/lang/Math.html#max(double,double)"><code>Math.max</code></a>.</div> + as if by calling <a href="../java.base/java/lang/Math.html#max(float,float)"><code>Math.max</code></a>.</div> Further out (JDK 19?) I think we should investigate the need for the `strict == false` case and/or give warnings (in javadoc) when the lookup is not exact. We should fix any cases in the JDK docs where that is the case, and/or consider removing support for `strict == false` or else make it an opt-in behavior somehow. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk18/pull/79
