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

[Martin Buchholz]

Thanks.

I continue to have a naive view where javac and javadoc are almost the
same program, e.g. document generation might just be another optional
output for javac.  And finding untidyness in the source code (whether
in javadoc comments or "real" code) is another job for javac.

I agree private serialization methods are special; they show up in the
generated html !


On Fri, Jun 19, 2020 at 12:51 PM Jonathan Gibbons
<jonathan.gibbons at oracle.com> wrote:
>
> 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.