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

[Jonathan Gibbons]

The reason for the different command line options is because javadoc
provides an inherent way of deciding which comments to process,
and javac does not: that's why javac has some additional options that
are not (currently) available in javadoc.

That being said, while I can see that there might be a way to support
an access control mechanism for javadoc, it will not be as easy as
one might like to think. Two problems come to mind:

1. the cascading accessibility issue: e.g. public methods in private types

2. serialization, which may use doc comments on /private/ fields
    if they are part of the serialized form and there are alternative
    sources of information, such as the @serial* tags.

-- Jon


On 6/19/20 12:06 PM, Martin Buchholz wrote:
> 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.