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&nbsp;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](JDK-8046095),
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](JDK-8046095), 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.