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

[Jonathan Gibbons]

On Thu, 7 Jul 2022 20:01:37 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This rights the wrongs of JDK-8008768. For more information, see the respective CSR.
>
> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 13 commits:
> 
>  - [feedback] revert some tests
>    
>    This addresses Jon's fair concerns on me aggressively removing some
>    test cases, that could still work.
>  - Merge remote-tracking branch 'jdk19/master' into 8287379
>  - Merge remote-tracking branch 'jdk19/master' into 8287379
>  - feedback: make method positive
>  - Merge remote-tracking branch 'jdk19/master' into 8287379
>  - Update DocTest
>    
>    1. Removes @inheritDoc from these type of declarations:
>         * class and interface
>         * constructor
>    2. Removes empty declarations.
>    3. Updates @apiNote, @implSpec and @implNote definitions to match those
>       of JDK API.
>    4. Fixes a few typos.
>  - Add tests
>  - Disallow @inheritDoc in type declarations
>    
>    This undoes undocumented changes introduced by 8008768.
>  - Do not warn on inline misuse
>    
>    The type of a declaration (module, class or interface, constructor,
>    method, etc.) for which a tag is applicable, is orthogonal to the type
>    of the tag (inline, block, bimodal).
>    
>    The code up the stack knows which type of tags it has collected. If
>    those tags are of type other than expected, it's a programming error.
>  - Doclint shouldn't warn on inapplicable conditions
>    
>    overview.html and doc-files/**/*.html files cannot have
>    a main description or be an empty comment. At the very least,
>    the check for being "an empty comment" for such files cannot be
>    performed by checking if the files contain any block tags. Block tags
>    are applicable to a program element, which those files are not.
>  - ... and 3 more: https://git.openjdk.org/jdk19/compare/3212dc9c...7d540c4e

> > 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](https://github.com/openjdk/jdk19/commit/7d540c4ede9e26b062f6fc977c5a310a95f1907d). 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?

That's not the right question.   The question is, how can we best replace the functionality of those tests. It's the relative link that's important, not the location.   Since the comment containing the relative link can no longer be placed on a top level declaration, they should be moved to a declaration where they are legal, such as on a method.

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

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