[This is not a review.] I want to make sure that we are doing the right thing.
Looking for definitions of doclint check groups, I found two relevant documents: the man page for javadoc(1) and JEP 172: DocLint. After skimming through the man page and the JEP, I can see the reasons for both keeping the status quo and for changing it like you proposed. Here's my question: is description a part of a tag syntax? Can we define this for each tag, in the Documentation Comment Specification for the Standard Doclet? To answer that, this sub-question might help. What is a practical difference between not having an @param tag for a parameter and having a descriptionless @param tag for that same parameter? The same goes for @throws/@exception. A more extreme case of that can be seen with @version, @since, and @return: those tags don't even have required components. P.S. Here's a separate observation. The @hidden block tag doesn't seem to complain about having "description", which its specification doesn't mention. -Pavel > On 18 Jun 2020, at 02:27, Jonathan Gibbons <jonathan.gibb...@oracle.com> > wrote: > > Please review a one word change in doclint, and associated test updates, > to recategorize "no description for TAG" in the MISSING (-Xdoclint:missing) > category instead of the SYNTAX (-Xdoclint:syntax) category. > > The proposed change is the result of being "surprised" all these messages > show up in the syntax category, when running doclint over all modules, > for each of its categories. > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8247815 > Webrev: http://cr.openjdk.java.net/~jjg/8247815/webrev.00/ >