RFR: 8325088: Overloads that differ in type parameters may be lost

[Jonathan Gibbons]

On Wed, 27 Mar 2024 21:56:48 GMT, Chen Liang <liach at 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 Thank you for reporting this issue.  The problem of linking to the API for different libraries generated with different versions of `javadoc` is indeed a difficult one.

I think the solution should be conceptually similar to the earlier problem you mentioned, addressed in [JDK-8297437](https://bugs.openjdk.org/browse/JDK-8297437).  In other words, the problem is not in the new-style ids, so much as in any links to pages with old(er)-style ids.

That being said, it would not be appropriate/reasonable for `javadoc` to scan HTML files to infer the style of `id` -- but there is an easier solution, which is to leverage the `element-list` file. (Previously, we leveraged the distinction between `package-list` and `element-list`).  The `element-list` file does not currently have any version or option info in it, implying any such files  it can be taken as implying version 1. Going forward, we can adapt the file to have a new kind of line as the first line, giving any extra info we need.

Links to other pages are generally handled by `HtmlLinkFactory` which eventually delegates to `Extern`.  `Extern` contains `boolean Extern.Item.useOldFormId` which I suspect should evolve from a `boolean` to an `enum` value or  `Set<Flag>` or something like that.

That being said, the current problem is slightly harder, because before, the problem was "just" about encoding the desired id into a form that was suitable for HTML 4.  Here, the choice is to use a completely different id. I suspect that the `memberName` parameter for `Extern.getExternalLink` may have to evolve from a `String` to something else -- maybe the underlying member `Element`, so that depending on the version of the remote library, we can generate the appropriate `id`.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2024156429