diff -r 22badc53802f -r bf24e33c7919 jdk/src/java.base/share/classes/java/io/PrintStream.java
--- a/jdk/src/java.base/share/classes/java/io/PrintStream.java Wed Aug 05 12:19:38 2015 -0700
+++ b/jdk/src/java.base/share/classes/java/io/PrintStream.java Thu Aug 06 13:20:13 2015 +0300
@@ -32,22 +32,22 @@
import java.nio.charset.UnsupportedCharsetException;
/**
- * A PrintStream
adds functionality to another output stream,
+ * A {@code PrintStream} adds functionality to another output stream,
* namely the ability to print representations of various data values
* conveniently. Two other features are provided as well. Unlike other output
- * streams, a PrintStream
never throws an
- * IOException
; instead, exceptional situations merely set an
- * internal flag that can be tested via the checkError
method.
- * Optionally, a PrintStream
can be created so as to flush
- * automatically; this means that the flush
method is
+ * streams, a {@code PrintStream} never throws an
+ * {@code IOException}; instead, exceptional situations merely set an
+ * internal flag that can be tested via the {@code checkError} method.
+ * Optionally, a {@code PrintStream} can be created so as to flush
+ * automatically; this means that the {@code flush} method is
* automatically invoked after a byte array is written, one of the
- * println
methods is invoked, or a newline character or byte
- * ('\n'
) is written.
+ * {@code println} methods is invoked, or a newline character or byte
+ * ({@code '\n'}) is written.
*
- *
All characters printed by a PrintStream
are converted into
- * bytes using the platform's default character encoding. The {@link
- * PrintWriter}
class should be used in situations that require writing
- * characters rather than bytes.
+ *
All characters printed by a {@code PrintStream} are converted into
+ * bytes using the platform's default character encoding.
+ * The {@link PrintWriter} class should be used in situations that require
+ * writing characters rather than bytes.
*
* @author Frank Yellin
* @author Mark Reinhold
@@ -142,8 +142,8 @@
* printed
* @param autoFlush A boolean; if true, the output buffer will be flushed
* whenever a byte array is written, one of the
- * println
methods is invoked, or a newline
- * character or byte ('\n'
) is written
+ * {@code println} methods is invoked, or a newline
+ * character or byte ({@code '\n'}) is written
*
* @see java.io.PrintWriter#PrintWriter(java.io.OutputStream, boolean)
*/
@@ -158,8 +158,8 @@
* printed
* @param autoFlush A boolean; if true, the output buffer will be flushed
* whenever a byte array is written, one of the
- * println
methods is invoked, or a newline
- * character or byte ('\n'
) is written
+ * {@code println} methods is invoked, or a newline
+ * character or byte ({@code '\n'}) is written
* @param encoding The name of a supported
*
* character encoding
@@ -371,21 +371,21 @@
/**
* Flushes the stream and checks its error state. The internal error state
- * is set to true
when the underlying output stream throws an
- * IOException
other than InterruptedIOException
,
- * and when the setError
method is invoked. If an operation
+ * is set to {@code true} when the underlying output stream throws an
+ * {@code IOException} other than {@code InterruptedIOException},
+ * and when the {@code setError} method is invoked. If an operation
* on the underlying output stream throws an
- * InterruptedIOException
, then the PrintStream
+ * {@code InterruptedIOException}, then the {@code PrintStream}
* converts the exception back into an interrupt by doing:
- *
+ ** or the equivalent. * - * @return{@code * Thread.currentThread().interrupt(); - *+ * }
true
if and only if this stream has encountered an
- * IOException
other than
- * InterruptedIOException
, or the
- * setError
method has been invoked
+ * @return {@code true} if and only if this stream has encountered an
+ * {@code IOException} other than
+ * {@code InterruptedIOException}, or the
+ * {@code setError} method has been invoked
*/
public boolean checkError() {
if (out != null)
@@ -398,11 +398,11 @@
}
/**
- * Sets the error state of the stream to true
.
+ * Sets the error state of the stream to {@code true}.
*
* This method will cause subsequent invocations of {@link - * #checkError()} to return true until {@link - * #clearError()} is invoked. + * #checkError()} to return {@code true} until + * {@link #clearError()} is invoked. * * @since 1.1 */ @@ -414,7 +414,7 @@ * Clears the internal error state of this stream. * *
This method will cause subsequent invocations of {@link
- * #checkError()} to return false until another write
+ * #checkError()} to return {@code false} until another write
* operation fails and invokes {@link #setError()}.
*
* @since 1.6
@@ -430,12 +430,12 @@
/**
* Writes the specified byte to this stream. If the byte is a newline and
- * automatic flushing is enabled then the flush
method will be
+ * automatic flushing is enabled then the {@code flush} method will be
* invoked.
*
*
Note that the byte is written as given; to write a character that
* will be translated according to the platform's default character
- * encoding, use the print(char)
or println(char)
+ * encoding, use the {@code print(char)} or {@code println(char)}
* methods.
*
* @param b The byte to be written
@@ -460,13 +460,13 @@
}
/**
- * Writes len
bytes from the specified byte array starting at
- * offset off
to this stream. If automatic flushing is
- * enabled then the flush
method will be invoked.
+ * Writes {@code len} bytes from the specified byte array starting at
+ * offset {@code off} to this stream. If automatic flushing is
+ * enabled then the {@code flush} method will be invoked.
*
*
Note that the bytes will be written as given; to write characters
* that will be translated according to the platform's default character
- * encoding, use the print(char)
or println(char)
+ * encoding, use the {@code print(char)} or {@code println(char)}
* methods.
*
* @param buf A byte array
@@ -559,13 +559,13 @@
/* Methods that do not terminate lines */
/**
- * Prints a boolean value. The string produced by {@link
- * java.lang.String#valueOf(boolean)}
is translated into bytes
+ * Prints a boolean value. The string produced by {@link
+ * java.lang.String#valueOf(boolean)} is translated into bytes
* according to the platform's default character encoding, and these bytes
* are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
- * @param b The boolean
to be printed
+ * @param b The {@code boolean} to be printed
*/
public void print(boolean b) {
write(b ? "true" : "false");
@@ -575,22 +575,22 @@
* Prints a character. The character is translated into one or more bytes
* according to the platform's default character encoding, and these bytes
* are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
- * @param c The char
to be printed
+ * @param c The {@code char} to be printed
*/
public void print(char c) {
write(String.valueOf(c));
}
/**
- * Prints an integer. The string produced by {@link
- * java.lang.String#valueOf(int)}
is translated into bytes
+ * Prints an integer. The string produced by {@link
+ * java.lang.String#valueOf(int)} is translated into bytes
* according to the platform's default character encoding, and these bytes
* are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
- * @param i The int
to be printed
+ * @param i The {@code int} to be printed
* @see java.lang.Integer#toString(int)
*/
public void print(int i) {
@@ -598,13 +598,13 @@
}
/**
- * Prints a long integer. The string produced by {@link
- * java.lang.String#valueOf(long)}
is translated into bytes
+ * Prints a long integer. The string produced by {@link
+ * java.lang.String#valueOf(long)} is translated into bytes
* according to the platform's default character encoding, and these bytes
* are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
- * @param l The long
to be printed
+ * @param l The {@code long} to be printed
* @see java.lang.Long#toString(long)
*/
public void print(long l) {
@@ -612,13 +612,13 @@
}
/**
- * Prints a floating-point number. The string produced by {@link
- * java.lang.String#valueOf(float)}
is translated into bytes
+ * Prints a floating-point number. The string produced by {@link
+ * java.lang.String#valueOf(float)} is translated into bytes
* according to the platform's default character encoding, and these bytes
* are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
- * @param f The float
to be printed
+ * @param f The {@code float} to be printed
* @see java.lang.Float#toString(float)
*/
public void print(float f) {
@@ -627,12 +627,12 @@
/**
* Prints a double-precision floating-point number. The string produced by
- * {@link java.lang.String#valueOf(double)}
is translated into
+ * {@link java.lang.String#valueOf(double)} is translated into
* bytes according to the platform's default character encoding, and these
- * bytes are written in exactly the manner of the {@link
- * #write(int)}
method.
+ * bytes are written in exactly the manner of the {@link
+ * #write(int)} method.
*
- * @param d The double
to be printed
+ * @param d The {@code double} to be printed
* @see java.lang.Double#toString(double)
*/
public void print(double d) {
@@ -643,24 +643,24 @@
* Prints an array of characters. The characters are converted into bytes
* according to the platform's default character encoding, and these bytes
* are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
* @param s The array of chars to be printed
*
- * @throws NullPointerException If s
is null
+ * @throws NullPointerException If {@code s} is {@code null}
*/
public void print(char s[]) {
write(s);
}
/**
- * Prints a string. If the argument is null
then the string
- * "null"
is printed. Otherwise, the string's characters are
+ * Prints a string. If the argument is {@code null} then the string
+ * {@code "null"} is printed. Otherwise, the string's characters are
* converted into bytes according to the platform's default character
* encoding, and these bytes are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
- * @param s The String
to be printed
+ * @param s The {@code String} to be printed
*/
public void print(String s) {
if (s == null) {
@@ -670,13 +670,13 @@
}
/**
- * Prints an object. The string produced by the {@link
- * java.lang.String#valueOf(Object)}
method is translated into bytes
+ * Prints an object. The string produced by the {@link
+ * java.lang.String#valueOf(Object)} method is translated into bytes
* according to the platform's default character encoding, and these bytes
* are written in exactly the manner of the
- * {@link #write(int)}
method.
+ * {@link #write(int)} method.
*
- * @param obj The Object
to be printed
+ * @param obj The {@code Object} to be printed
* @see java.lang.Object#toString()
*/
public void print(Object obj) {
@@ -689,8 +689,8 @@
/**
* Terminates the current line by writing the line separator string. The
* line separator string is defined by the system property
- * line.separator
, and is not necessarily a single newline
- * character ('\n'
).
+ * {@code line.separator}, and is not necessarily a single newline
+ * character ({@code '\n'}).
*/
public void println() {
newLine();
@@ -698,10 +698,10 @@
/**
* Prints a boolean and then terminate the line. This method behaves as
- * though it invokes {@link #print(boolean)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(boolean)} and then
+ * {@link #println()}.
*
- * @param x The boolean
to be printed
+ * @param x The {@code boolean} to be printed
*/
public void println(boolean x) {
synchronized (this) {
@@ -712,10 +712,10 @@
/**
* Prints a character and then terminate the line. This method behaves as
- * though it invokes {@link #print(char)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(char)} and then
+ * {@link #println()}.
*
- * @param x The char
to be printed.
+ * @param x The {@code char} to be printed.
*/
public void println(char x) {
synchronized (this) {
@@ -726,10 +726,10 @@
/**
* Prints an integer and then terminate the line. This method behaves as
- * though it invokes {@link #print(int)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(int)} and then
+ * {@link #println()}.
*
- * @param x The int
to be printed.
+ * @param x The {@code int} to be printed.
*/
public void println(int x) {
synchronized (this) {
@@ -740,10 +740,10 @@
/**
* Prints a long and then terminate the line. This method behaves as
- * though it invokes {@link #print(long)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(long)} and then
+ * {@link #println()}.
*
- * @param x a The long
to be printed.
+ * @param x a The {@code long} to be printed.
*/
public void println(long x) {
synchronized (this) {
@@ -754,10 +754,10 @@
/**
* Prints a float and then terminate the line. This method behaves as
- * though it invokes {@link #print(float)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(float)} and then
+ * {@link #println()}.
*
- * @param x The float
to be printed.
+ * @param x The {@code float} to be printed.
*/
public void println(float x) {
synchronized (this) {
@@ -768,10 +768,10 @@
/**
* Prints a double and then terminate the line. This method behaves as
- * though it invokes {@link #print(double)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(double)} and then
+ * {@link #println()}.
*
- * @param x The double
to be printed.
+ * @param x The {@code double} to be printed.
*/
public void println(double x) {
synchronized (this) {
@@ -782,8 +782,8 @@
/**
* Prints an array of characters and then terminate the line. This method
- * behaves as though it invokes {@link #print(char[])}
and
- * then {@link #println()}
.
+ * behaves as though it invokes {@link #print(char[])} and
+ * then {@link #println()}.
*
* @param x an array of chars to print.
*/
@@ -796,10 +796,10 @@
/**
* Prints a String and then terminate the line. This method behaves as
- * though it invokes {@link #print(String)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(String)} and then
+ * {@link #println()}.
*
- * @param x The String
to be printed.
+ * @param x The {@code String} to be printed.
*/
public void println(String x) {
synchronized (this) {
@@ -812,10 +812,10 @@
* Prints an Object and then terminate the line. This method calls
* at first String.valueOf(x) to get the printed object's string value,
* then behaves as
- * though it invokes {@link #print(String)}
and then
- * {@link #println()}
.
+ * though it invokes {@link #print(String)} and then
+ * {@link #println()}.
*
- * @param x The Object
to be printed.
+ * @param x The {@code Object} to be printed.
*/
public void println(Object x) {
String s = String.valueOf(x);
@@ -830,11 +830,13 @@
* A convenience method to write a formatted string to this output stream
* using the specified format string and arguments.
*
- *
An invocation of this method of the form out.printf(format, - * args) behaves in exactly the same way as the invocation + *
An invocation of this method of the form + * {@code out.printf(format, args)} behaves + * in exactly the same way as the invocation * - *
- * out.format(format, args)+ *
{@code + * out.format(format, args) + * }* * @param format * A format string as described in The Java™ Virtual Machine Specification. * The behaviour on a - * null argument depends on the conversion. * * @throws java.util.IllegalFormatException @@ -861,7 +863,7 @@ * formatter class specification. * * @throws NullPointerException - * If the format is null + * If the {@code format} is {@code null} * * @return This output stream * @@ -875,15 +877,17 @@ * A convenience method to write a formatted string to this output stream * using the specified format string and arguments. * - *
An invocation of this method of the form out.printf(l, format, - * args) behaves in exactly the same way as the invocation + *
An invocation of this method of the form + * {@code out.printf(l, format, args)} behaves + * in exactly the same way as the invocation * - *
- * out.format(l, format, args)+ *
{@code + * out.format(l, format, args) + * }* * @param l * The {@linkplain java.util.Locale locale} to apply during - * formatting. If l is null then no localization + * formatting. If {@code l} is {@code null} then no localization * is applied. * * @param format @@ -898,7 +902,7 @@ * limited by the maximum dimension of a Java array as defined by * The Java™ Virtual Machine Specification. * The behaviour on a - * null argument depends on the conversion. * * @throws java.util.IllegalFormatException @@ -911,7 +915,7 @@ * formatter class specification. * * @throws NullPointerException - * If the format is null + * If the {@code format} is {@code null} * * @return This output stream * @@ -941,7 +945,7 @@ * limited by the maximum dimension of a Java array as defined by * The Java™ Virtual Machine Specification. * The behaviour on a - * null argument depends on the conversion. * * @throws java.util.IllegalFormatException @@ -954,7 +958,7 @@ * formatter class specification. * * @throws NullPointerException - * If the format is null + * If the {@code format} is {@code null} * * @return This output stream * @@ -983,7 +987,7 @@ * * @param l * The {@linkplain java.util.Locale locale} to apply during - * formatting. If l is null then no localization + * formatting. If {@code l} is {@code null} then no localization * is applied. * * @param format @@ -998,7 +1002,7 @@ * limited by the maximum dimension of a Java array as defined by * The Java™ Virtual Machine Specification. * The behaviour on a - * null argument depends on the conversion. * * @throws java.util.IllegalFormatException @@ -1011,7 +1015,7 @@ * formatter class specification. * * @throws NullPointerException - * If the format is null + * If the {@code format} is {@code null} * * @return This output stream * @@ -1037,21 +1041,22 @@ /** * Appends the specified character sequence to this output stream. * - *
An invocation of this method of the form out.append(csq) + *
An invocation of this method of the form {@code out.append(csq)} * behaves in exactly the same way as the invocation * - *
- * out.print(csq.toString())+ *
{@code + * out.print(csq.toString()) + * }* - *
Depending on the specification of toString for the - * character sequence csq, the entire sequence may not be - * appended. For instance, invoking then toString method of a + *
Depending on the specification of {@code toString} for the + * character sequence {@code csq}, the entire sequence may not be + * appended. For instance, invoking then {@code toString} method of a * character buffer will return a subsequence whose content depends upon * the buffer's position and limit. * * @param csq - * The character sequence to append. If csq is - * null, then the four characters "null" are + * The character sequence to append. If {@code csq} is + * {@code null}, then the four characters {@code "null"} are * appended to this output stream. * * @return This output stream @@ -1070,18 +1075,20 @@ * Appends a subsequence of the specified character sequence to this output * stream. * - *
An invocation of this method of the form out.append(csq, start, - * end) when csq is not null, behaves in + *
An invocation of this method of the form + * {@code out.append(csq, start, end)} when + * {@code csq} is not {@code null}, behaves in * exactly the same way as the invocation * - *
- * out.print(csq.subSequence(start, end).toString())+ *
{@code + * out.print(csq.subSequence(start, end).toString()) + * }* * @param csq * The character sequence from which a subsequence will be - * appended. If csq is null, then characters - * will be appended as if csq contained the four - * characters "null". + * appended. If {@code csq} is {@code null}, then characters + * will be appended as if {@code csq} contained the four + * characters {@code "null"}. * * @param start * The index of the first character in the subsequence @@ -1093,9 +1100,9 @@ * @return This output stream * * @throws IndexOutOfBoundsException - * If start or end are negative, start - * is greater than end, or end is greater than - * csq.length() + * If {@code start} or {@code end} are negative, {@code start} + * is greater than {@code end}, or {@code end} is greater than + * {@code csq.length()} * * @since 1.5 */ @@ -1108,11 +1115,12 @@ /** * Appends the specified character to this output stream. * - *
An invocation of this method of the form out.append(c) + *
An invocation of this method of the form {@code out.append(c)} * behaves in exactly the same way as the invocation * - *
- * out.print(c)+ *
{@code + * out.print(c) + * }* * @param c * The 16-bit character to append