RFR: JDK-8267204: Expose access to underlying streams in Reporter

[Jonathan Gibbons]

On Thu, 27 May 2021 10:15:43 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review an update to `jdk.javadoc/jdk.javadoc.doclets.Reporter` to add 3 new methods and to improve the descriptions of other parts of the interface.
>> 
>> The new methods provide access to the underlying streams (informally, for standard output and diagnostic output), and a new `report` method to report diagnostics at an arbitrary position in a file being read by a doclet, or a taglet within a doclet.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java line 98:
> 
>> 96:      * @param file    the file
>> 97:      * @param start   the beginning of the enclosing range
>> 98:      * @param pos     the position
> 
> Unless there's a reason not to, I would prefer to have an inequality clearly showing how these 3 indexes relate to each other. For example, is it the case that `{@code start <= pos <= end}`?

Will do. I had this in an earlier draft. I backed out because I also wanted to bound `start` and `end` but it is not common in API to indicate indices must be non-negative, and it is an IO operation (and potential exception) to verify the upper bound is valid.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Messager.java line 435:
> 
>> 433: 
>> 434:     /**
>> 435:      * Prints the error and warning counts, if any, to. the diagnostic writer
> 
> Move period from after "to" to the end of the sentence.

Wow, how did that typo come about? :-)

-------------

PR: https://git.openjdk.java.net/jdk/pull/4216