On 09/26/2013 06:00 PM, Martin Buchholz wrote:
On Thu, Sep 26, 2013 at 5:45 PM, Jonathan Gibbons
<jonathan.gibb...@oracle.com <mailto:jonathan.gibb...@oracle.com>> wrote:
The new diagnostics are generated by the new doclint feature which
is available from the javac and javadoc command lines.
When invoked from javadoc, it only checks the comments being used
for the docs that you are generating. So, if you are generating
docs for just your public and protected methods, doclint will not
(or should not) warn about your package-private and private
methods. The decision of which doc comments to check comes from
the standard javadoc command line options used to select the
elements to document, i.e. -private, -package, -protected, -public.
When invoked from javac, you actually have somewhat more
versatility. The -Xdoclint command line option for javac actually
allows you to specify different access levels for different types
of check, so you could check syntax errors for all comments but
only check for missing comments on public and protected elements.
With respect to your specific comments, I wonder if there is a
typo in your message, because it doesn't quite make sense as written:
We would like to use javadoc style, and have the javadoc tool
warn us of "real bugs" in our javadoc (even private methods) BUT
we don't want javadoc to enforce the same high standards for
public methods, e.g. don't require all of the @param for type
parameters.
The word "public" in "the same high standards for public methods"
makes more sense to me if you meant "private" here. Which did you
really mean?
I really meant "BUT we don't want javadoc, when run against private
methods, to enforce the same high standards as for public methods"
E.g. for maintainers, adding @param or @returns (or @SuppressWarnings)
to the method below is not an improvement.
/**
* Returns the trigger time of a delayed action.
*/
private long triggerTime(long delay, TimeUnit unit) {
return triggerTime(unit.toNanos((delay < 0) ? 0 : delay));
}
Martin,
OK, yes, that is more what I was expecting you meant. We ran across
exactly the same situation when applying doclint to our own code.
If you invoke doclint from javac, you should have the flexibility you
are looking for in the -Xdoclint option and its suboptions. You can set
a high standard for public and protected methods, and a lower standard
(or no standard) for private and package-private methods.
-- Jon
