Experimental new utility to detect issues in javadoc comments

[Jonathan Gibbons]

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/