Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
Closed
Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
0d81752
JDK-8267204: Expose access to underlying streams in Reporter
jonathan-gibbons May 20, 2021
989c56b
JDK-8267202: Improve doc spec for doclet Reporter
jonathan-gibbons May 20, 2021
b8ffb0e
Merge from upstream/master
jonathan-gibbons May 25, 2021
4b14375
JDK-8267204: Expose access to underlying streams in Reporter
jonathan-gibbons May 26, 2021
772274e
Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter
jonathan-gibbons May 26, 2021
3d7f0ad
Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter
jonathan-gibbons May 27, 2021
11d31ed
add new test; update stream handling
jonathan-gibbons May 27, 2021
1ed9ace
extend Messages to provide convenient access to the new Reporter.repo…
jonathan-gibbons May 27, 2021
df7075e
Address review feedback
jonathan-gibbons May 27, 2021
bfc7b18
Address review feedback
jonathan-gibbons Jun 2, 2021
fc69fe0
Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter
jonathan-gibbons Jun 2, 2021
153ce9b
Fix typos
jonathan-gibbons Jun 2, 2021
25791c5
Fix typos
jonathan-gibbons Jun 2, 2021
521ffe9
Fix typos
jonathan-gibbons Jun 2, 2021
694e105
Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter
jonathan-gibbons Jun 2, 2021
dc3e98d
Merge remote-tracking branch 'upstream/master' into jdk-8267204-reporter
jonathan-gibbons Jun 4, 2021
78e811b
Update copyright years
jonathan-gibbons Jun 4, 2021
1b70b66
use printRawLines instead of println for correct newline handline on …
jonathan-gibbons Jun 4, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
@@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -25,41 +25,125 @@

package jdk.javadoc.doclet;

import java.io.PrintWriter;
import java.util.Locale;
import javax.lang.model.element.Element;
import javax.tools.Diagnostic;
import javax.tools.FileObject;

import com.sun.source.util.DocTreePath;

/**
* This interface provides error, warning and notice reporting.
* Interface for reporting diagnostics and other messages.
*
* <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}.
Copy link
Member

@pavelrappo pavelrappo Jun 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"at" looks misplaced here.

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Jun 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* Other messages may be written directly to one of two streams that are informally
* for use by "standard output" and "diagnostic output", where "standard output"
* means the output that is the expected result of executing some operation,
* such as the command-line help that is generated when using a {@code --help} option,
* and "diagnostic output" refers to any errors, warnings and other output that is
* a side-effect of executing the operation.
*
* <p>The exact manner in which diagnostics are output is unspecified and depends
* on the enclosing context. For example:
* <ul>
* <li>The {@link javax.tools.DocumentationTool} API allows a client to specify a
* {@link javax.tools.DiagnosticListener} to which diagnostics will be
* {@link javax.tools.DiagnosticListener#report reported}. If no listener is specified,
* diagnostics will be written to a given stream, or to {@code System.err} if no such
* stream is provided.
* <li>The {@link java.util.spi.ToolProvider} API allows a client to specify
* the streams to be used for reporting standard and diagnostic output.
* </ul>
*
* @since 9
*/
public interface Reporter {

/**
* Print error message and increment error count.
* Prints a diagnostic message.
*
* @param kind specify the diagnostic kind
* @param msg message to print
* @param kind the kind of diagnostic
* @param message the message to be printed
*/
void print(Diagnostic.Kind kind, String msg);
void print(Diagnostic.Kind kind, String message);

/**
* Print an error message and increment error count.
* Prints a diagnostic message related to a tree node in a documentation comment.
*
* @param kind specify the diagnostic kind
* @param path the DocTreePath of item where the error occurs
* @param msg message to print
* @param kind the kind of diagnostic
* @param path the path for the tree node
* @param message the message to be printed
*/
void print(Diagnostic.Kind kind, DocTreePath path, String msg);
void print(Diagnostic.Kind kind, DocTreePath path, String message);

/**
* Print an error message and increment error count.
* Prints a diagnostic message related to an element.
*
* @param kind specify the diagnostic kind
* @param e the Element for which the error occurs
* @param msg message to print
* @param kind the kind of diagnostic
* @param element the element
* @param message the message to be printed
*/
void print(Diagnostic.Kind kind, Element e, String msg);
void print(Diagnostic.Kind kind, Element element, String message);

/**
* Prints a diagnostic message related to a position within a range of characters in a file.
* The positions are all 0-based character offsets from the beginning of content of the file.
* The positions should satisfy the relation {@code start <= pos <= end}.
*
* @param kind the kind of diagnostic
* @param file the file
* @param start the beginning of the enclosing range
* @param pos the position
jonathan-gibbons marked this conversation as resolved.
Show resolved Hide resolved
* @param end the end of the enclosing range
* @param message the message to be printed
jonathan-gibbons marked this conversation as resolved.
Show resolved Hide resolved
*
* @since 17
*/
void print(Diagnostic.Kind kind, FileObject file, int start, int pos, int end, String message);


Copy link
Member

@pavelrappo pavelrappo Jun 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Delete one line.

/**
* Returns a writer that can be used to write non-diagnostic output,
* or {@code null} if no such writer is available.
*
* @apiNote
* The value may or may not be the same as that returned by {@link #getDiagnosticWriter()}.
*
* @implSpec
* This implementation returns {@code null}.
* The implementation provided by the {@code javadoc} tool to
* {@link Doclet#init(Locale, Reporter) initialize} a doclet
* always returns a non-{@code null} value.
*
* @return the writer
* @since 17
*/
default PrintWriter getStandardWriter() {
return null;
}

/**
* Returns a writer that can be used to write diagnostic output,
* or {@code null} if no such writer is available.
*
* @apiNote
* The value may or may not be the same as that returned by {@link #getStandardWriter()}.
*
* @implSpec
* This implementation returns {@code null}.
* The implementation provided by the {@code javadoc} tool to
* {@link Doclet#init(Locale, Reporter) initialize} a doclet
* always returns a non-{@code null} value.
*
* @return the writer
* @since 17
*/
default PrintWriter getDiagnosticWriter() {
return null;
}

}
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@

import javax.lang.model.element.Element;
import javax.tools.Diagnostic;
import javax.tools.FileObject;

import com.sun.source.util.DocTreePath;
import jdk.javadoc.doclet.Reporter;
@@ -76,8 +77,8 @@ public Resources getResources() {
/**
* Reports an error message to the doclet's reporter.
*
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message.
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void error(String key, Object... args) {
report(ERROR, resources.getText(key, args));
@@ -86,22 +87,35 @@ public void error(String key, Object... args) {
/**
* Reports an error message to the doclet's reporter.
*
* @param path a path identifying the position to be included with
* the message
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message.
* @param path a path identifying the position to be included with the message
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void error(DocTreePath path, String key, Object... args) {
report(ERROR, path, resources.getText(key, args));
}

/**
* Reports an error message to the doclet's reporter.
*
* @param fo the file object to be associated with the message
* @param start the start of a range of characters to be associated with the message
* @param pos the position to be associated with the message
* @param end the end of a range of characters to be associated with the message
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void error(FileObject fo, int start, int pos, int end, String key, Object... args) {
report(ERROR, fo, start, pos, end, resources.getText(key, args));
}

// ***** Warnings *****

/**
* Reports a warning message to the doclet's reporter.
*
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message.
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void warning(String key, Object... args) {
report(WARNING, resources.getText(key, args));
@@ -110,10 +124,9 @@ public void warning(String key, Object... args) {
/**
* Reports a warning message to the doclet's reporter.
*
* @param path a path identifying the position to be included with
* the message
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message.
* @param path a path identifying the position to be included with the message
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void warning(DocTreePath path, String key, Object... args) {
if (configuration.showMessage(path, key)) {
@@ -124,28 +137,44 @@ public void warning(DocTreePath path, String key, Object... args) {
/**
* Reports a warning message to the doclet's reporter.
*
* @param e an element identifying the declaration whose position should
* to be included with the message
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message.
* @param e an element identifying the declaration whose position should
* be included with the message
Copy link
Member

@pavelrappo pavelrappo Jun 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Jun 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void warning(Element e, String key, Object... args) {
if (configuration.showMessage(e, key)) {
report(WARNING, e, resources.getText(key, args));
}
}

/**
* Reports a warning message to the doclet's reporter.
*
* @param fo the file object to be associated with the message
* @param start the start of a range of characters to be associated with the message
* @param pos the position to be associated with the message
* @param end the end of a range of characters to be associated with the message
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void warning(FileObject fo, int start, int pos, int end, String key, Object... args) {
report(WARNING, fo, start, pos, end, resources.getText(key, args));
}

// ***** Notices *****

/**
* Reports an informational notice to the doclet's reporter.
* The message is written directly to the reporter's diagnostic stream.
*
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message.
* @param key the name of a resource containing the message to be printed
* @param args optional arguments to be replaced in the message
*/
public void notice(String key, Object... args) {
if (!configuration.getOptions().quiet()) {
report(NOTE, resources.getText(key, args));
// Note: we do not use report(NOTE, ...) which would prefix the output with "Note:"
reporter.getDiagnosticWriter().println(resources.getText(key, args));
}
}

@@ -162,4 +191,8 @@ private void report(Diagnostic.Kind k, DocTreePath p, String msg) {
private void report(Diagnostic.Kind k, Element e, String msg) {
reporter.print(k, e, msg);
}

private void report(Diagnostic.Kind k, FileObject fo, int start, int pos, int end, String msg) {
reporter.print(k, fo, start, pos, end, msg);
}
}