[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

Marked as reviewed by jjg (Reviewer).

test/langtools/jdk/javadoc/doclet/InheritDocForUserTags/DocTest.java line 57:

> 55:         // javadoc does not report an exit code for an internal exception (!)
> 56:         // so monitor stderr for stack dumps.
> 57:         checkOutput(Output.STDERR, false, "at com.sun");

This is a general comment for a followup discussion and future work.

Should we have a standard default-on check in `JavadocTester` for "no stack traces"? That is, the equivalent of this line here. We could model such a check on `checkLinks` or `checkAccessibility` such that a hypothetical `checkNoCrashes` could be disabled in the (rare?) cases that they might be expected. (For example, checking the tool/doclet behavior when a crash does occur.)

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

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