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

[Martin Buchholz]

It's surprising that javadoc's Xdoclint flag differs from javac's.
I was expecting javadoc's to also have access level control.
I'd like all javadoc comments to be checked for correctness whenever
they are written, but not require them when non-public.

My command line for javadoc16 doing jsr166 development looks like this:

Executing '/home/martin/jdk/jdk16/bin/javadoc' with arguments:
'-d'
'/home/martin/jsr166/pristine/build/docs'
'-overview'
'/home/martin/jsr166/pristine/src/main/intro.html'
'-protected'
'-Xdocrootparent'
'https://docs.oracle.com/en/java/javase/11/docs'
'-Xmaxerrs'
'1000'
'-Xmaxwarns'
'1000'
'-quiet'
'-XDignore.symbol.file=true'
'-html5'
'-Xdoclint:all,-missing'
'--patch-module=java.base=/home/martin/jsr166/pristine/src/main'
'--override-methods=summary'
'-tag'
'jls:a:See <cite>The Java™ Language Specification</cite>:'
'-tag'
'implSpec:a:Implementation Requirements:'
'-tag'
'implNote:a:Implementation Note:'
'-tag'
'apiNote:a:API Note:'
'-version'
'-author'
'-sourcepath'
'/home/martin/jsr166/pristine/src/main'
'-link'
'https://docs.oracle.com/en/java/javase/11/docs/api/'
'-source'
'16'

On Fri, Jun 19, 2020 at 11:51 AM Pavel Rappo <pavel.rappo at oracle.com> wrote:
>
> One can invoke DocLint in several different ways. Depending on the way they choose, the behaviour will slightly differ.
>
> To understand what happens, I need to know how you invoke DocLint. Would you be able to provide the exact command lines or the code snippets (if you invoke DocLint programmatically)?
>
> -Pavel
>
> > On 19 Jun 2020, at 19:27, Martin Buchholz <martinrb at google.com> 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.
>