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

[Jonathan Gibbons]

On Mon, 11 Jul 2022 15:35:12 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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
>
> 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.)

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

While the bug and this test are about "no crashes", we should ensure that we have positive tests elsewhere for the actual output generated, assuming that no crash occurred.

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

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