RFR [15] JDK-8247815: doclint: recategorize "no description for ..." as MISSING, not SYNTAX

[Pavel Rappo]

[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.gibbons at 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/
>