On 6/19/20 12:59 PM, Martin Buchholz wrote:
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.
Generally agreed, and it's good for you to occasionally remind us of that.
But while the tools are very similar, there are differences around the
edges.
For example, javac will never read package.html files (I wish we could get
folk to transition to package-info.java files!) and javac doesn't know about
custom tags/taglets. And, javadoc has its own world of options for
identifying elements to be "compiled" into documentation.
I agree private serialization methods are special; they show up in the
generated html !
I can see a possible goal where access controls for doclint in javadoc
merely restrict the set of messages that are generated. In other words,
for generating public documentation, the doclint access level should
be set to "all", meaning "all elements being documented, including
private serialization stuff". If individuals want to raise the access level
for reported issues, that's their choice and is semantically equivalent
to running `grep -v` on the output ;-)
On Fri, Jun 19, 2020 at 12:51 PM Jonathan Gibbons
<jonathan.gibb...@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.
