JEP 172: DocLint

Summary

Provide a means to detect errors in Javadoc comments early in the development cycle and in a way that is easily linked back to the source code.

Goals

The javadoc tool currently provides little to no checking of the content of Javadoc comments, and what checking it does provide does not link back to the source code, and is typically overlooked by developers. As a result, errors are typically propagated into the generated documentation files which can affect the specifications in those files. We need better tools to help detect more errors, earlier, such that reported issues are easy to fix.

Typical errors can be grouped into various categories:

• Bad syntax, such as unescaped characters ("<") or unmatched parentheses ("{@foo")
• Bad HTML, such as invalid or missing tags or attributes
• Bad references, such as referencing a non-existent type with @see, or a non-existent parameter with @param
• Accessibility errors, such as a missing summary or caption from a table
• Missing info, such as an undocumented parameter

The goal is to detect and report the majority of common errors made by developers writing Javadoc comments, such that the generated output files will generally pass external validation tools, such as HTML and accessibility conformance tools.

Any errors should be reported in a way similar to that of common compilers, such that the messages can easily be consumed by suitable editors and IDEs, to help developers easily locate and fix the errors.

A user should be able to configure the tool to select or restrict the checks that are made. For example, only report instances of bad syntax, or only report errors on public and protected methods.

Non-Goals

It is not a goal to detect all issues such that we can guarantee that the generated documentation will pass any nominated validation tool.

Motivation

The API specifications for the Java SE platform are primarily based on documents generated by the javadoc tool. Errors have been found in API specifications that can be traced back to errors in the original Javadoc comments. By providing tools to detect and report such errors in a timely manner, we can reduce the risk of publishing incorrect specifications.

In addition, by ensuring that the output from the javadoc tool is conformant to prevailing standards, we reduce the risk that it will not work on some combinations of platform and browser.

These days it is generally regarded as important for generated documentation to conform to accessibility guidelines, such as Section 508. We need better tools to help detect probable errors at a point in the development cycle when it is easy to fix such issues.

Existing formal tools, such as HTML and accessibility conformance checkers can only be applied to the output of the javadoc tool. This makes it hard to relate any error messages back to the position in the original source text. We need tools that can report errors in the context of the original source.

Description

The tool will build upon the "DocTree API" described in JEP 105, which itself an extension to the javac "Tree API" now available in the com.sun.source package. The DocTree API provides a way to get a "syntax tree" for the elements of a Javadoc comment.

The tool will scan source files, looking for declarations that have associated Javadoc comments. It will use the DocTree API to parse those comments, and will then analyse the resulting AST looking for issues.

The tool could be made available in a number of ways.

1. Since it is processing Javadoc comments, the natural way to present the tool could be as a doclet. The user would specify to use the doclet on the javadoc command line, using the existing javadoc -doclet and -docletpath options. The doclet would provide additional options to select the categories of issue to be reported, in a manner similar to the existing javac -Xlint option.

   A variant of this option would be to "hard-wire" the tool into the existing standard doclet. This allows a simpler way for a user to invoke the tool, but does imply a performance penalty, since the standard doclet does not yet utilize the DocTree API. (That would be a laudable goal for a separate project.) However, javadoc is already slow (!!) and parsing comments with the DocTree API is fast, so the perceived slow down may not be too onerous.

   Either way, using the javadoc tool to generate documentation is normally an afterthought that happens late in the tool chain. Many developers do not even run the tool, and so such a solution fails to meet the goal of reporting issues in a timely manner.

2. The tool could be made available as a new standalone tool. This would imply additional work, such as providing a launcher, and related man pages. Earlier experience with the apt annotation processing tool has shown that it is hard to introduce a new tool into the typical developer tool chain.

3. The tool could be "hooked into" javac, such that the developer can choose to see messages about issues in Javadoc comments at the same time that they see messages about issues in their source code. This means that enabling the tool can be as easy as adding another option to the javac command line. Since the tool will support configuration options of its own, the use of the tool is not a binary choice that can be added into the existing javac -Xlint mechanism. Instead, it is proposed that the tool will use a similar but different option, -Xdoclint or -Xdoclint:args.

4. The tool could also be hooked into an IDE like NetBeans, which already uses a variant of javac to provide the feedback about errors in the source editor window. Modifying the NetBeans source editor is out of scope, but the tool should not preclude someone else integrating the tool into IDEs such that we get "red squiggly lines" for more than just spelling errors in Javadoc comments.

It is expected that we will do some combination of options 1 and 3, making the tool available via javac and javadoc.

Alternatives

The problem of ensuring that the javadoc tool generates valid HTML output could be addressed by post-processing the output semi-automatically through a tool like htmltidy. However, generating "clean" HTML from invalid input simply covers over the problem, and does not help address the fundamental problem of finding (and fixing) the errors in the original source text.

Testing

We should continue to run such formal validation tools as are available, on documentation generated from the OpenJDK source code. We should then check that any errors reported by those tools are also detected and reported by the new tool.

Risks and Assumptions

If the feature is to be included in JDK 8, the primary risk is the availability of resources. The mitigation plan would be to make the tool available separately for now, for inclusion in a later release of the platform.

Dependences

Depends on JEP 105, which is now available in JDK 8 build 66 (M5).

Impact

• Accessibility: Will help improve accessibility of our generated documentation
• Documentation: Will help improve conformance to HTML standards of our generated documentation.