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

[Pavel Rappo]

On Thu, 27 May 2021 03:20:34 GMT, Jonathan Gibbons <jjg 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.

Update the copyright years and you're good to go.

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java line 42:

> 40:  * and may additionally be associated with an {@link Element element},
> 41:  * a {@link DocTreePath tree node} in a documentation comment,
> 42:  * or at an arbitrary position in a given {@link FileObject file}.

"at" looks misplaced here.

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java line 108:

> 106:     void print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message);
> 107: 
> 108: 

Delete one line.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java line 141:

> 139:      *
> 140:      * @param e    an element identifying the declaration whose position should
> 141:      *             be included with the message

I see what you've changed: one of these words needed to go. Either "should" or "to". You chose "to". Unless you did it for semantical reasons, I note that this file uses "to be" in the vast majority of similar cases.

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

Marked as reviewed by prappo (Reviewer).

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