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

[Jonathan Gibbons]

I've filed a JBS issue for this:

https://bugs.openjdk.java.net/browse/JDK-8247951

-- Jon

On 6/19/20 11:35 AM, Jonathan Gibbons wrote:
> Martin,
>
> In javac, you have that explicit level of control.  From the 
> command-line help
>
>   -Xdoclint:(all|none|[-]<group>)[/<access>]
>         Enable or disable specific checks for problems in javadoc 
> comments,
>         where <group> is one of accessibility, html, missing, 
> reference, or syntax,
>         and <access> is one of public, protected, package, or private.
>
> In javadoc, the rule is to check the comments being accessed by 
> javadoc ...
> so if you don't want to write comments in javadoc format, don't run 
> javadoc
> on those comments!
>
> -- Jon
>
> On 6/19/20 11:27 AM, Martin Buchholz wrote:
>> Relatedly, today I noticed warnings for missing comments on non-public
>> elements with javadoc16 that did not appear in javadoc11.
>>
>> CompletableFuture.java:1718: warning: no comment
>>      static final class AsyncSupply<T> extends ForkJoinTask<Void>
>>                   ^
>>
>> Naturally I added the flag -Xdoclint:all,-missing
>> BUT I'd like to be able to control which access levels require 
>> javadoc comments.
>> Few style guides will want to require javadoc comments on private 
>> elements.