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. ------------- Commit messages: - JDK-8272374: doclint should report missing "body" comments Changes: https://git.openjdk.java.net/jdk/pull/5106/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=5106&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8272374 Stats: 281 lines in 37 files changed: 152 ins; 10 del; 119 mod Patch: https://git.openjdk.java.net/jdk/pull/5106.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/5106/head:pull/5106 PR: https://git.openjdk.java.net/jdk/pull/5106
