On Fri, 13 Aug 2021 09:20:19 GMT, Hannes Wallnöfer <hann...@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. > > 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`. ------------- PR: https://git.openjdk.java.net/jdk/pull/5106
