CodeTools proposal: doccheck

[Martin Buchholz]

Thanks!  I was wondering why there were two different tools, and this is an
excellent explanation.

On Tue, Nov 13, 2018 at 1:56 PM, Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> 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
>
>