JDK-8267204: Expose access to underlying streams in Reporter #4216

jonathan-gibbons · 2021-05-27T03:20:34Z

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.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8267204: Expose access to underlying streams in Reporter

Reviewers

Pavel Rappo (@pavelrappo - Reviewer) ⚠️ Review applies to 521ffe9

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/4216/head:pull/4216
$ git checkout pull/4216

Update a local copy of the PR:
$ git checkout pull/4216
$ git pull https://git.openjdk.java.net/jdk pull/4216/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 4216

View PR using the GUI difftool:
$ git pr show -t 4216

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/4216.diff

bridgekeeper · 2021-05-27T03:20:54Z

👋 Welcome back jjg! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2021-05-27T03:23:14Z

@jonathan-gibbons The following label will be automatically applied to this pull request:

javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

…rt method

jonathan-gibbons · 2021-05-27T04:30:35Z

/csr

openjdk · 2021-05-27T04:31:11Z

@jonathan-gibbons this pull request will not be integrated until the CSR request JDK-8267279 for issue JDK-8267204 has been approved.

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

pavelrappo

Thank you so much for doing this, Jon. Although this PR is good by itself, it will be particularly useful for snippets (JEP 413). While I'm still reviewing this PR, you could have a look at the comments I have made so far.

pavelrappo · 2021-05-27T09:24:41Z

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

- * This interface provides error, warning and notice reporting.
+ * Interface for reporting diagnostics and other messages.
+ *
+ * <p>Diagnostics consist of a diagnostic {@link Diagnostic.Kind kind} and a message,


Consider moving "diagnostic" into the @link label: {@link Diagnostic.Kind diagnostic kind}.

pavelrappo · 2021-05-27T09:29:54Z

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

+     * Prints a diagnostic message.
+     *
+     * @param kind    the kind of diagnostic
+     * @param message message to print


Prepend "message to print" with "the". Alternatively, consider using "the message to be printed", which seems typical in this file.

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

pavelrappo · 2021-05-27T10:18:22Z

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

+     * @param pos   the position to be associated with the end
+     * @param end   the end of a range of characters to be associated with the end
+     * @param key   the name of a resource containing the message to be printed
+     * @param args  optional arguments to be replaced in the message.


Remove the trailing period.

pavelrappo · 2021-05-27T10:21:02Z

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

+     * @param pos   the position to be associated with the end
+     * @param end   the end of a range of characters to be associated with the end
+     * @param key   the name of a resource containing the message to be printed
+     * @param args  optional arguments to be replaced in the message.


Same here: remove the trailing period.

pavelrappo · 2021-05-27T10:26:13Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Messager.java

@@ -389,16 +432,21 @@ public boolean hasWarnings() {
    }

    /**
-     * Prints the error and warning counts, if any.
+     * 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? :-)

test/langtools/jdk/javadoc/doclet/testReporterStreams/TestReporterStreams.java

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

pavelrappo · 2021-05-27T10:46:20Z

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

+     * @param start the start of a range of characters to be associated with the end
+     * @param pos   the position to be associated with the end
+     * @param end   the end of a range of characters to be associated with the end


"Associated with end"? I believe it should either be "error" or "message", not "end".

pavelrappo · 2021-05-27T10:47:08Z

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

+     * @param start the start of a range of characters to be associated with the end
+     * @param pos   the position to be associated with the end
+     * @param end   the end of a range of characters to be associated with the end


Same here: "associated with the end"?

pavelrappo · 2021-05-27T10:55:31Z

As far as I understand #4077 will be closed as superseded by this PR?

jonathan-gibbons · 2021-05-27T14:40:09Z

As far as I understand #4077 will be closed as superseded by this PR?

Yes, I've closed the PR.

mlbridge · 2021-06-02T21:23:00Z

Webrevs

pavelrappo

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

pavelrappo · 2021-06-04T20:12:59Z

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

+ * <p>Diagnostics consist of a {@link Diagnostic.Kind diagnostic kind} and a message,
+ * and may additionally be associated with an {@link Element element},
+ * a {@link DocTreePath tree node} in a documentation comment,
+ * or at an arbitrary position in a given {@link FileObject file}.


"at" looks misplaced here.

When I wrote it, it looked right; now, I agree with you.

pavelrappo · 2021-06-04T20:21:16Z

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java

+
+

Delete one line.

pavelrappo · 2021-06-04T20:30:30Z

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

+     * @param e    an element identifying the declaration whose position should
+     *             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.

The wording is correct, but I agree it the overall phrasing is inconsistent in form with similar phrases elsewhere, because in this context it uses "the declaration whose position ..."

It's an internal API, so I don't want to get too hung up on it. I'll change the form to be more like the others.

openjdk · 2021-06-04T20:36:00Z

@jonathan-gibbons This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8267204: Expose access to underlying streams in Reporter

Reviewed-by: prappo

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 1 new commit pushed to the master branch:

48dc72b: 8268272: Remove JDK-8264874 changes because Graal was removed.

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

…Windows address review feedback

jonathan-gibbons · 2021-06-05T00:04:08Z

/integrate

openjdk · 2021-06-05T00:05:43Z

@jonathan-gibbons Since your change was applied there have been 3 commits pushed to the master branch:

76b54a1: 8263512: [macos_aarch64] issues with calling va_args functions from invoke_native
4e6748c: 8267687: ModXNode::Ideal optimization is better than Parse::do_irem
48dc72b: 8268272: Remove JDK-8264874 changes because Graal was removed.

Your commit was automatically rebased without conflicts.

Pushed as commit 6ff978a.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

jonathan-gibbons added 7 commits May 20, 2021 14:15

JDK-8267204: Expose access to underlying streams in Reporter

0d81752

JDK-8267202: Improve doc spec for doclet Reporter

989c56b

Merge from upstream/master

b8ffb0e

JDK-8267204: Expose access to underlying streams in Reporter

4b14375

Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter

772274e

Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter

3d7f0ad

add new test; update stream handling

11d31ed

openjdk bot added the javadoc javadoc-dev@openjdk.org label May 27, 2021

extend Messages to provide convenient access to the new Reporter.repo…

1ed9ace

…rt method

openjdk bot added the csr Pull request needs approved CSR before integration label May 27, 2021

liach reviewed May 27, 2021

View reviewed changes

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java Show resolved Hide resolved

pavelrappo reviewed May 27, 2021

View reviewed changes

pavelrappo mentioned this pull request May 27, 2021

JDK-8267204: Expose access to underlying streams in Reporter #4077

Closed

3 tasks

jonathan-gibbons added 7 commits May 27, 2021 08:30

Address review feedback

df7075e

Address review feedback

bfc7b18

Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter

fc69fe0

Fix typos

153ce9b

Fix typos

25791c5

Fix typos

521ffe9

Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter

694e105

jonathan-gibbons marked this pull request as ready for review June 2, 2021 21:17

openjdk bot added rfr Pull request is ready for review and removed csr Pull request needs approved CSR before integration labels Jun 2, 2021

jonathan-gibbons added 2 commits June 4, 2021 12:54

Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter

dc3e98d

Update copyright years

78e811b

pavelrappo approved these changes Jun 4, 2021

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jun 4, 2021

use printRawLines instead of println for correct newline handline on …

1b70b66

…Windows address review feedback

openjdk bot closed this Jun 5, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jun 5, 2021

jonathan-gibbons deleted the jdk-8267204-reporter branch October 20, 2021 22:06

JDK-8267204: Expose access to underlying streams in Reporter #4216

JDK-8267204: Expose access to underlying streams in Reporter #4216

jonathan-gibbons commented May 27, 2021 •

edited by openjdk bot

bridgekeeper bot commented May 27, 2021

openjdk bot commented May 27, 2021

jonathan-gibbons commented May 27, 2021

openjdk bot commented May 27, 2021

pavelrappo left a comment

pavelrappo May 27, 2021

pavelrappo May 27, 2021

pavelrappo May 27, 2021

pavelrappo May 27, 2021

pavelrappo May 27, 2021

jonathan-gibbons May 27, 2021

pavelrappo May 27, 2021

pavelrappo May 27, 2021

pavelrappo commented May 27, 2021

jonathan-gibbons commented May 27, 2021

mlbridge bot commented Jun 2, 2021 •

edited

pavelrappo left a comment

pavelrappo Jun 4, 2021

jonathan-gibbons Jun 4, 2021

pavelrappo Jun 4, 2021

pavelrappo Jun 4, 2021

jonathan-gibbons Jun 4, 2021

openjdk bot commented Jun 4, 2021 •

edited

jonathan-gibbons commented Jun 5, 2021

openjdk bot commented Jun 5, 2021

		* @param e an element identifying the declaration whose position should
		* be included with the message

JDK-8267204: Expose access to underlying streams in Reporter #4216

JDK-8267204: Expose access to underlying streams in Reporter #4216

Conversation

jonathan-gibbons commented May 27, 2021 • edited by openjdk bot

Progress

Issue

Reviewers

Reviewing

bridgekeeper bot commented May 27, 2021

openjdk bot commented May 27, 2021

jonathan-gibbons commented May 27, 2021

openjdk bot commented May 27, 2021

pavelrappo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pavelrappo commented May 27, 2021

jonathan-gibbons commented May 27, 2021

mlbridge bot commented Jun 2, 2021 • edited

Webrevs

pavelrappo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openjdk bot commented Jun 4, 2021 • edited

jonathan-gibbons commented Jun 5, 2021

openjdk bot commented Jun 5, 2021

jonathan-gibbons commented May 27, 2021 •

edited by openjdk bot

mlbridge bot commented Jun 2, 2021 •

edited

openjdk bot commented Jun 4, 2021 •

edited