RFR: JDK-8164094: javadoc allows to create a @link to a non-existent method [v2]

[Jan Lahoda]

On Tue, 12 Dec 2023 12:42:41 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Please review a simple fix in `JavacTrees` to only look up member references in the enclosing type if the reference does not contain an explicit type name. For example, `@see #method()` in a a doc comment of class `Outer.Inner` should find method `Outer.method()`, but `@see Inner#method()` should not (regardless of comment location).
>
> Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
> 
>  - Merge branch 'master' into JDK-8164094
>  - Additional test
>  - JDK-8164094: javadoc allows to create a @link to a non-existent method

For "normal" field or method (simple-name) lookup, the same-named field or method from the enclosing scope is shadowed by the declaration in the current ("nested") scope (JLS 6.4.1). The "nested" scope includes inherited fields and methods. So, even for fields, it might be preferable to first search supertypes, and only then enclosing scopes.

There is a caveat: the inheritance rules are a bit complex, like for example `private`, inaccessible or hidden(*) fields are not inherited (JLS 8.3); rules for methods are even a bit more complex (JLS 8.4.8). I.e. if we just change the search order, we may end up looking up a private field from a supertype, instead of the more correct field from an enclosing scope.

(*) hidden fields are not really an issue here.

There's also one more specialty for methods: if there's any method of name `m` in a given scope, even if it is not applicable due to parameter types, the search ends in that scope, and does not go to the enclosing scopes (a method named `m` shadows all methods named `m` with any parameters in the enclosing scope). (JLS 6.4.1)

I am not sure how strictly correct javadoc needs to be, but if we want to get closer to the normal "simple-name" lookup, we would probably need to tighten up the code.

I was briefly looking whether we could reuse the standard lookup - might be doable for fields, but not sure about methods. Would need some more investigations, I am afraid.

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

PR Comment: https://git.openjdk.org/jdk/pull/17069#issuecomment-1853948123