New methods and clarifications for the doclet Reporter interface

Summary

Provide new methods and clarifications for the jdk.javadoc.doclet.Reporter interface.

Problem

1. Historically, javadoc has not specified the use of streams for diagnostics and other output. This follows from the then-prevailing practice for javac, and annotation processors. javac has since improved the support for specifying streams, and javadoc should do the same, and this extends to doclets used by javadoc.

2. The existing specification is incorrect in a number of places: most notably the specification refers to "error messages and error counts" even though the method may apply to arbitrary diagnostic kinds.

3. The existing API can only report diagnostics associated with the position of an element or a node in a documentation comment tree.

Solution

1. New methods are added to Reporter to provide access to the "standard" and "diagnostics" streams used by the javadoc tool. The methods are on an interface. The specification allows the default implementation to return null, but specifies that the methods will not return null for the instance of Reporter used by the javadoc tool to initialize doclets.

2. The existing comments are corrected and clarified.

3. A new method is added that can report a diagnostic at an arbitrary position in a range of characters in a specified file.

Specification

A specdiff is attached. A copy of the changes can be seen here: http://cr.openjdk.java.net/~jjg/8267204/specdiff.00/jdk.javadoc/jdk/javadoc/doclet/Reporter.html