Experimental new utility to detect issues in javadoc comments

[Jonathan Gibbons]

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/