On Mon, 27 Jun 2022 22:04:42 GMT, Jonathan Gibbons <[email protected]> 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
