CodeTools proposal: doccheck

[Jonathan Gibbons]

Name: doccheck

Summary: A utility to provide a number of checks for HTML files in the 
JDK documentation for API and related specifications.

Proposed by: Jonathan Gibbons

Rationale:

This utility has been written to provide simple fast, checking for 
various aspects of the JDK documentation, such as invalid HTML, broken 
links, bad characters, and so on. It is useful to compare/contrast this 
with the "doclint" support in javac and javadoc. The following is from 
the proposed documentation [1]


        DocCheck vs. DocLint

    DocLint is a utility built into javac and javadoc that performs some
    amount of checking of the content of documentation comments.
    Although there is some overlap in functionality, the two utilities
    are different and each has its own strengths and weaknesses.

      *

        ||DocCheck checks the end result of any generated documentation.
        This includes content from all sources, such as documentation
        comments, the standard doclet, user-provided taglets, and
        content supplied via command-line options. Because it is
        analyzing complete HTML pages, it can do more complete checks
        than can DocLint.

        However, when problems are found in generated pages, it can be
        harder to track down exactly where the problem needs to be
        fixed. (This was a major motivation for writing DocLint.)

      *

        DocLint checks the content of documentation comments. This makes
        it very easy to identify the exact position of any issues that
        may be found. DocLint can also detect some semantic errors in
        documentation comments that DocCheck cannot detect, such as
        using an |@return| tag in a method returning |void|, or a
        |@param| tag describing a non-existent parameter.

        But by its nature, DocLint cannot report on problems such as
        missing links, or errors in user-provided custom taglets, or
        problems in the standard doclet itself. It also cannot reliably
        detect errors in documentation comments at the boundaries
        between content in a documentation comment and content generated
        by a custom taglet.

        DocLint does not currently check the content of any HTML pages
        in |doc-files| subdirectories. These files are simply copied to
        the output directory, along with any other files in such
        directories.


[1] http://cr.openjdk.java.net/~jjg/doccheck/doc/doccheck.html