Experimental new utility to detect issues in javadoc comments (original) (raw)
Jonathan Gibbons jonathan.gibbons at oracle.com
Fri Sep 28 16:28:55 PDT 2012
- Previous message: JEP 105: DocTree API: implementation preview
- Next message: javac 7 is able to generate inner class that can't be verified
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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:
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 ...}".
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.
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".
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".
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/
- Previous message: JEP 105: DocTree API: implementation preview
- Next message: javac 7 is able to generate inner class that can't be verified
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]