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