[OpenJDK 2D-Dev] RFR: JDK-8272374: doclint should report missing "body" comments
kcr at openjdk.java.net
Fri Aug 13 15:46:27 UTC 2021
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.
I tested this by using it to generate the JavaFX docs. We have 62 new warnings for methods with empty descriptions that we otherwise would not have easily found.
Marked as reviewed by kcr (Author).
More information about the 2d-dev