I've posted another preview of the new utility to detect issues in
javadoc comments [1].
Changes since I last posted here:
* the utility has been renamed to "doclint"
* the categories have been shuffled a bit and are now
reference show places where comments contain incorrect
references to Java source code elements
syntax show basic syntax errors within comments
html show issues with HTML tags and attributes
accessibility show issues for accessibility
missing show issues with missing documentation
* more issues are detected
* you can limit the checks to comments of public/private/protected
declarations
* I've posted a jar file, along with the latest webrev. To use the jar file,
java -Xbootclasspath/p:doclint.jar ...options... ...files
Use -help to see the options.
The tool requires JDK 8 to run.
Thanks to those folk who have been testing the tool, and fixing the
errors in
JDK doc comments that have been identified.
-- Jon
On 09/28/2012 04:28 PM, Jonathan Gibbons wrote:
I have posted a preview of an experimental new utility to detect
issues in javadoc comments [1], based on the recently announced [2]
implementation of JEP 105: DocTree API.
The utility is currently called "doccheck", since it is at least
partially inspired by the old Sun "doccheck" doclet, which has
otherwise fallen by the wayside.
The primary goal of the tool is detect issues that may give rise to
output from javadoc which may be either invalid or not meet
web-accessible guidelines, and to report those issues in a
dev-friendly way, to make it easy to fix them. This includes being
fast to run, and providing accurate location information.
The tool can be run stand-alone, or as an annotation processor within
javac, or as a doclet inside javadoc. In time, it may be appropriate
to hook it more directly into javac, such that you can (optionally)
check for bad javadoc comments at the same time that you compile your
code. One possibility would be to have javac support something like
-Xdoclint.
The tool supports different categories of issues:
1. Syntax errors, like the direct use of '<', '>', and '&' in a
javadoc comment, when they should instead written as entities, or
enclosed within "{@code...}" or "{@literal ...}".
2. Reference errors, relating to references to source code elements
from within a javadoc comment. Common examples are references to
missing or mistyped names in @param, @see and {@link...} tags.
3. HTML tag errors, such as the use of unknown tags, mismatched tags
and interleaved tags. Indirectly, it also includes use of '<' and '>'
when they ought to be escaped, such as in "List<String>".
4. HTML attribute errors, such as the use of unknown or deprecated
attributed. Many attributes are being deprecated in favor of using CSS
instead, and the tool can report such occurrences. Indirectly, this
category also includes use of '<' and '>' when they ought to be
escaped, such as in "class Foo<A extends List>".
The tool will check files given on the command line; any classes to
which those files refer may also be provided on the source or class
path. Currently, it checks /all/ javadoc comments, not just commented
on public and protected elements: after all, a specification for a
non-existent parameter is bad code, whatever the accessibility of the
element being documented.
In the "reports" directory of [1], you can see examples of the output
from the tool for many top level java.* and javax.* packages. For
simplicity, I've provided separate files for each package for each of
the categories of issue that can be generated. And finally, in the
spirit of seeing how easy it is to work with the reports and fix the
issues, I've posted a webrev of changes to fix up issues in the
langtools repo [3]. There were more than a few chuckles and sighs at
the bit rot, cut 'n paste errors and "misunderstandings" that were
present in the code base.
-- Jon
[1] http://cr.openjdk.java.net/~jjg/8000103/
[2]
http://mail.openjdk.java.net/pipermail/compiler-dev/2012-September/004752.html
[3] http://cr.openjdk.java.net/~jjg/8000208/
