CodeTools proposal: doccheck

[Jonathan Gibbons]

:-)

Yes, both are useful; DocCheck is more thorough but it can be tedious to 
map errors back to source code. It's also the case that since we moved 
to unified documentation, we've temporarily-it-seems-like-forever 
disabled a lot of the DocLint checks in the build. Overall, the JDK docs 
are in pretty good shape, so we should look at turning up the DocLint 
knobs again.

-- Jon


On 11/14/2018 11:16 PM, Martin Buchholz wrote:
> 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 <mailto: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
>     <http://cr.openjdk.java.net/%7Ejjg/doccheck/doc/doccheck.html>
>
>