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.ra...@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 <marti...@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.
