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

[Pavel Rappo]

Thanks for the explanation. The webrev looks good. As a bonus I learned a bit about doclint.

-Pavel

> On 18 Jun 2020, at 19:35, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Hi Pavel,
> 
> Based on your questions here and off-line discussions, I think that recategorizing the message is the right thing to do.
> 
> My only reservation is that we already have lots of missing comments in the JDK API docs, and so the messages that will be affected by this change might get overlooked (or suppressed with -Xdoclint:missing) when they should be fixed.  But, that shouldn't affect us reporting these messages "correctly".
> 
> More answers inline below.
> 
> -- Jon
> 
> 
> On 6/18/20 7:20 AM, Pavel Rappo wrote:
>> [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?
> 
> Well, yes, it is part of the syntax, and is given as such in the specification. That being said, the spec maybe doesn't clarify what happens if the description is empty.
> 
>> 
>> 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.
> 
> In an alternate reality, we might put the doc comment on parameters and somehow on the return type, and in that reality, there would be no question that the category for a missing comment would be MISSING. In other words, at least for @param, @return, @throws, the tag can be thought as providing the position of "where" to "attach" the comment. suggesting that it is better to report it as MISSING when that part of the tag is empty.
> 
> 
>> 
>> 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.
> That may be a separate bug against the @hidden tag. It might need some research on the discussion that took place when we added the tag.
>> 
>> -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/
>>>