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