[jdk19] RFR: 8287379: Using @inheritDoc in an inapplicable context shouldn't crash javadoc [v3]

[Pavel Rappo]

On Mon, 27 Jun 2022 22:04:42 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This is a general response to the edits in `testRelativeLinks`.
> 
> There are various circumstances in which relative links need to be fixed up, all related to taking content containing links from one place and using it in another. These include:
> 
> * the first sentence of a class or interface comment, showing up in a package summary,
> * the first sentence of a package comment showing up in a module summary,
> * info being inherited from one file into another by means of `{@inherotDoc}`,
> * etc ... info showing up on "other pages", like serialized-form, constant-values.
> 
> While I do not expect a full review of all these use cases, the _intent_ of the use of `{@inheritDoc}` in `testRelativeLinks` was good and well-meaning, even if the specific instances are now seen in hindsight as bad. Bottom line: we should not simply remove the bad cases: we should replace them with good cases, meaning, test relative links with `{@inheritDoc}` used in method descriptions and/or tags.

I accept that I nixed some tests overly aggressively. I carefully returned them back in 7d540c4. Note that since `{@inheritDoc}` is no longer allowed on a class or interface declaration, I cannot return all of the tests I deleted.

If fixing up relative links needs to be tested for a top-level declaration, then they have to be tested some other way, outside of the context of this PR; do you agree?

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

PR: https://git.openjdk.org/jdk19/pull/54