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

[Jonathan Gibbons]

On Wed, 13 Dec 2023 14:53:57 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>>> Should this issue have a CSR for the behavioral change?
>> 
>> My understanding of the issue is that the lookup of explicit-class member references in enclosing classes was an unintended consequence of doing the same for classless references from within nested classes. So I consider this a bug fix, not a feature change (even though it unfortunately changes javadoc to become stricter in what it accepts).
>> 
>> Actually, the feature of extending member reference lookup to enclosing classes is not specified in the taglet spec, which only says this:
>> 
>>> When the reference is to a member of the same class as that containing the documentation comment, all parts of the reference up to and including the # may be omitted, although the '#' may be retained for clarity.
>> 
>> This could be extended to include enclosing classes, but this is existing behaviour, not changed by this issue.
>
> @hns would you be able to create a linked bug to track that lookup order issue?

I note the preceding discussion including @pavelrappo's notes about order of lookup, and the separate issue to pursue this further.

It's also not clear to me that the statement in the description is "right":  _but @see Inner#method() should not_ 
If `Inner.method()` has a meaning (making allowances for `static` or not, etc) in nearby code, then shouldn't `Inner#method()` have a similar meaning?

I think that we should
1.  determine the lexical scope for the doc comment
2. follow the JLS rules as much as possible, with matching examples for doc comments and Java code as much as possible
3. clearly specify that doc comment names follow the JLS rules, except when they're not, and clearly specify any exceptions to those rules

All that is out of scope for here, and can be handled in [JDK-8324320](https://bugs.openjdk.org/browse/JDK-8324320), so I have one last question before I add my approval (or Pavel can lower the `/reviewer` count):
Does this change affect the published/latest JDK API documentation in any way?  I'm guessing not, but we've been surprised before.

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

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