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

[Jonathan Gibbons]

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/
>>