On Fri, 13 Aug 2021 03:51:23 GMT, Jonathan Gibbons <j...@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). PR: https://git.openjdk.java.net/jdk/pull/5106