On Mon, 16 Aug 2021 17:08:13 GMT, Jonathan Gibbons <j...@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
