RFR: JDK-8272374: doclint should report missing "body" comments

[Hannes Wallnöfer]

On Fri, 13 Aug 2021 03:51:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a relatively simple update to have doclnt check for empty "descriptions" -- the body of a doc comment, before the block tags.
> 
> It is already the case that doclint checks for missing/empty descriptions in block tags, like @param, @return, etc.
> 
> There are three cases to consider:
> 
> * The comment itself is missing: this was already checked and reported as "missing comment".
> * The comment is present, but is empty ... this seems relatively unlikely, but is nevertheless checked and reported as "empty comment".
> * The comment is present but only has block tags. This is not always a problem, since the description may be inherited, for example, in an overriding method, but when it is an issue, it is reported as "no initial description". 
> 
> No diagnostic is reported if the description is missing but the first tag is `@deprecated`, because in this case, javadoc will use the body of the `@deprecated` tag for the summary. See [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA) and the corresponding entry in the summary table to see an example of this situation.
> 
> Diagnostics are reported if the declaration is not an overriding method and does not begin with `@deprecated`.  This occurs in a number of places in the `java.desktop` module, often where the doc comment is of the form `/** @return _description_ */`.  To suppress those warnings for now, the `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop` module.  To see the effects of this anti-pattern, look at the empty descriptions for [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
> 
> Many of the doclint tests needed to be updated, because of their over-simplistic minimal comments. It was not possible, in general, to avoid updating the source code while preserving line numbers, so in many cases, the golden `*.out` files had to be updated as well.
> 
> A new test is added, focussing on the different forms of empty/missing descriptions, as described above.

Looks good. One thing I wonder about is why you only look for `@deprecated` in the first block tag. I guess it is just a convention to add this tag at the first position?

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?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 204:

> 202:                     // because javadoc will use the content of that tag in summary tables.
> 203:                     if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
> 204:                         env.messages.report(MISSING, Kind.WARNING, tree, "dc.empty.description");

Is there a reason to not use `reportMissing` here?

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

Marked as reviewed by hannesw (Reviewer).

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