[OpenJDK 2D-Dev] RFR: JDK-8272374: doclint should report missing "body" comments

[Jonathan Gibbons]

On Mon, 16 Aug 2021 17:08:13 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 203:
>> 
>>> 201:                     // Don't report an empty description if the comment begins with @deprecated,
>>> 202:                     // because javadoc will use the content of that tag in summary tables.
>>> 203:                     if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
>> 
>> Why do we only check the first block tag here?
>
> Various reasons, 
> 1. It seems the convention is to simply prefix an existing comment with `@deprecated` or to replace the existing body description with `@deprecated reason-why-deprecated`
> 2. This is only for the case when there is no body description; it seems hard to imagine that someone would start a comment with `@see` `@param` `@return` etc and then have the `@deprecated` tag.
> 
> That being said, it would be easy enough to change the code to check for any instance of `@deprecated`.

Given that the downstream code does not impose any ordering restrictions on the tags, it is probably with doing the same here.

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

PR: https://git.openjdk.java.net/jdk/pull/5106