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

[Jonathan Gibbons]

On Mon, 27 Jun 2022 19:15:16 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 268:
>> 
>>> 266:     // Checks if the passed tree path does NOT correspond to an entity, such as
>>> 267:     // the overview file and doc-files/**/*.html files.
>>> 268:     private boolean notPseudoElement(TreePath p) {
>> 
>> The use of a predicate named `not...` seems confusing and leads to various double negatives;  it would be easier to read if this was `isPseudoElement` even if that means an extra `!` at the call site.
>
> We have public `Stream.noneMatch()`, `Files.notExists()`, `Objects.nonNull()`, and many more non-public methods that answer a negative question; but I'll change this one if you think that it will improve readability.

> It worries me that we are removing support for a feature that had explicit positive tests.

We discussed this offline at length.   The tests are not specifically for the feature, but instead, they are tests for a different feature (relative links) in a variety of situations, including the suspect case of `{@inheritDoc}`.

It might be worth investigating whether we can write tests for relative links when `{@inheritDoc}` is used in a legal position, such as on a method declaration.

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

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