harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [8/10] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
Date Fri, 01 May 2009 08:09:01 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintWriter.java Fri May  1 08:08:59 2009
@@ -26,25 +26,25 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * PrintWriter is a class which takes either an OutputStream or Writer and
- * provides convenience methods for printing common data types in a human
- * readable format on the stream. No IOExceptions are thrown by this class.
- * Instead, callers should call checkError() to see if a problem has been
- * encountered in this Writer.
+ * Wraps either an existing {@link OutputStream} or an existing {@link Writer}
+ * and provides convenience methods for printing common data types in a human
+ * readable format. No {@code IOException} is thrown by this class. Instead,
+ * callers should use {@link #checkError()} to see if a problem has occurred in
+ * this writer.
  */
 public class PrintWriter extends Writer {
     /**
-     * The writer to output data to.
+     * The writer to print data to.
      */
     protected Writer out;
 
     /**
-     * indicates whether or not this PrintWriter has incurred an error.
+     * Indicates whether this PrintWriter is in an error state.
      */
     private boolean ioError;
 
     /**
-     * indicates whether or not this PrintWriter should flush its contents after
+     * Indicates whether or not this PrintWriter should flush its contents after
      * printing a new line.
      */
     private boolean autoflush;
@@ -53,54 +53,64 @@
             .doPrivileged(new PriviAction<String>("line.separator")); //$NON-NLS-1$
 
     /**
-     * Constructs a new PrintWriter on the OutputStream <code>out</code>. All
-     * writes to the target can now take place through this PrintWriter. By
-     * default, the PrintWriter is set to not autoflush when println() is
-     * called.
+     * Constructs a new {@code PrintWriter} with {@code out} as its target
+     * stream. By default, the new print writer does not automatically flush its
+     * contents to the target stream when a newline is encountered.
      * 
      * @param out
-     *            the the OutputStream to provide convenience methods on.
+     *            the target output stream.
+     * @throws NullPointerException
+     *             if {@code out} is {@code null}.
      */
     public PrintWriter(OutputStream out) {
         this(new OutputStreamWriter(out), false);
     }
 
     /**
-     * Constructs a new PrintWriter on the OutputStream <code>out</code>. All
-     * writes to the target can now take place through this PrintWriter. By
-     * default, the PrintWriter is set to not autoflush when println() is
-     * called.
+     * Constructs a new {@code PrintWriter} with {@code out} as its target
+     * stream. The parameter {@code autoflush} determines if the print writer
+     * automatically flushes its contents to the target stream when a newline is
+     * encountered.
      * 
      * @param out
-     *            the the OutputStream to provide convenience methods on.
+     *            the target output stream.
      * @param autoflush
-     *            whether to flush when println() is called.
+     *            indicates whether contents are flushed upon encountering a
+     *            newline sequence.
+     * @throws NullPointerException
+     *             if {@code out} is {@code null}.
      */
     public PrintWriter(OutputStream out, boolean autoflush) {
         this(new OutputStreamWriter(out), autoflush);
     }
 
     /**
-     * Constructs a new PrintWriter on the Writer <code>wr</code>. All writes
-     * to the target can now take place through this PrintWriter. By default,
-     * the PrintWriter is set to not autoflush when println() is called.
+     * Constructs a new {@code PrintWriter} with {@code wr} as its target
+     * writer. By default, the new print writer does not automatically flush its
+     * contents to the target writer when a newline is encountered.
      * 
      * @param wr
-     *            the Writer to provide convenience methods on.
+     *            the target writer.
+     * @throws NullPointerException
+     *             if {@code wr} is {@code null}.
      */
     public PrintWriter(Writer wr) {
         this(wr, false);
     }
 
     /**
-     * Constructs a new PrintWriter on the given writer. All writes to the
-     * target can now take place through this PrintWriter. By default, the
-     * PrintWriter is set to not autoflush when println() is called.
+     * Constructs a new {@code PrintWriter} with {@code out} as its target
+     * writer. The parameter {@code autoflush} determines if the print writer
+     * automatically flushes its contents to the target writer when a newline is
+     * encountered.
      * 
      * @param wr
-     *            the Writer to provide convenience methods on.
+     *            the target writer.
      * @param autoflush
-     *            whether to flush when println() is called.
+     *            indicates whether to flush contents upon encountering a
+     *            newline sequence.
+     * @throws NullPointerException
+     *             if {@code out} is {@code null}.
      */
     public PrintWriter(Writer wr, boolean autoflush) {
         super(wr);
@@ -109,16 +119,19 @@
     }
 
     /**
-     * Constructs a new PrintWriter on the File <code>file</code>. The
-     * automatic flushing is set to <code>false</code>. An intermediate
-     * <code>OutputStreamWriter</code> will use the default for the current
-     * JVM instance charset to encode characters.
+     * Constructs a new {@code PrintWriter} with {@code file} as its target. The
+     * virtual machine's default character set is used for character encoding.
+     * The print writer does not automatically flush its contents to the target
+     * file when a newline is encountered. The output to the file is buffered.
      * 
      * @param file
-     *            This writer's buffered destination.
+     *            the target file. If the file already exists, its contents are
+     *            removed, otherwise a new file is created.
      * @throws FileNotFoundException
-     *             If there is no such a file or some other error occurs due to
-     *             the given file opening.
+     *             if an error occurs while opening or creating the target file.
+     * @throws SecurityException
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      */
     public PrintWriter(File file) throws FileNotFoundException {
         this(new OutputStreamWriter(new BufferedOutputStream(
@@ -126,20 +139,25 @@
     }
 
     /**
-     * Constructs a new PrintWriter on the File <code>file</code>. The
-     * automatic flushing is set to <code>false</code>. An intermediate
-     * <code>OutputStreamWriter</code> will use a charset with the given name
-     * <code>csn</code> to encode characters.
+     * Constructs a new {@code PrintWriter} with {@code file} as its target. The
+     * character set named {@code csn} is used for character encoding.
+     * The print writer does not automatically flush its contents to the target
+     * file when a newline is encountered. The output to the file is buffered.
      * 
      * @param file
-     *            This writer's buffered destination.
+     *            the target file. If the file already exists, its contents are
+     *            removed, otherwise a new file is created.
      * @param csn
-     *            A charset name.
+     *            the name of the character set used for character encoding.
      * @throws FileNotFoundException
-     *             If there is no such a file or some other error occurs due to
-     *             the given file opening.
+     *             if an error occurs while opening or creating the target file.
+     * @throws NullPointerException
+     *             if {@code csn} is {@code null}.
+     * @throws SecurityException
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      * @throws UnsupportedEncodingException
-     *             If a charset with the given name is not supported.
+     *             if the encoding specified by {@code csn} is not supported.
      */
     public PrintWriter(File file, String csn) throws FileNotFoundException,
             UnsupportedEncodingException {
@@ -148,39 +166,47 @@
     }
 
     /**
-     * Constructs a new PrintWriter on a file with the given file name
-     * <code>fileName</code>. The automatic flushing is set to
-     * <code>false</code>. An intermediate <code>OutputStreamWriter</code>
-     * will use the default for the current JVM instance charset to encode
-     * characters.
+     * Constructs a new {@code PrintWriter} with the file identified by {@code
+     * fileName} as its target. The virtual machine's default character set is
+     * used for character encoding. The print writer does not automatically
+     * flush its contents to the target file when a newline is encountered. The
+     * output to the file is buffered.
      * 
      * @param fileName
-     *            The name of file which is this writer's buffered destination.
+     *            the target file's name. If the file already exists, its
+     *            contents are removed, otherwise a new file is created.
      * @throws FileNotFoundException
-     *             If there is no such a file or some other error occurs due to
-     *             the given file opening.
+     *             if an error occurs while opening or creating the target file.
+     * @throws SecurityException
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      */
     public PrintWriter(String fileName) throws FileNotFoundException {
         this(new OutputStreamWriter(new BufferedOutputStream(
                 new FileOutputStream(fileName))), false);
     }
 
-    /**
-     * Constructs a new PrintWriter on a file with the given file name
-     * <code>fileName</code>. The automatic flushing is set to
-     * <code>false</code>. An intermediate <code>OutputStreamWriter</code>
-     * will use a charset with the given name <code>csn</code> to encode
-     * characters.
+     /**
+     * Constructs a new {@code PrintWriter} with the file identified by {@code
+     * fileName} as its target. The character set named {@code csn} is used for
+     * character encoding. The print writer does not automatically flush its
+     * contents to the target file when a newline is encountered. The output to
+     * the file is buffered.
      * 
      * @param fileName
-     *            The name of file which is this writer's buffered destination.
+     *            the target file's name. If the file already exists, its
+     *            contents are removed, otherwise a new file is created.
      * @param csn
-     *            A charset name.
+     *            the name of the character set used for character encoding.
      * @throws FileNotFoundException
-     *             If there is no such a file or some other error occurs due to
-     *             the given file opening.
+     *             if an error occurs while opening or creating the target file.
+     * @throws NullPointerException
+     *             if {@code csn} is {@code null}.
+     * @throws SecurityException
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      * @throws UnsupportedEncodingException
-     *             If a charset with the given name is not supported.
+     *             if the encoding specified by {@code csn} is not supported.
      */
     public PrintWriter(String fileName, String csn)
             throws FileNotFoundException, UnsupportedEncodingException {
@@ -189,12 +215,12 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this PrintWriter has
-     * encountered an error. If so, the receiver should probably be closed since
-     * further writes will not actually take place. A side effect of calling
-     * checkError is that the target Writer is flushed.
+     * Flushes this writer and returns the value of the error flag.
      * 
-     * @return boolean has an error occurred in this PrintWriter.
+     * @return {@code true} if either an {@code IOException} has been thrown
+     *         previously or if {@code setError()} has been called;
+     *         {@code false} otherwise.
+     * @see #setError()
      */
     public boolean checkError() {
         if (out != null) {
@@ -204,9 +230,8 @@
     }
 
     /**
-     * Close this PrintWriter. This implementation flushes and then closes the
-     * target writer. If an error occurs, set an error in this PrintWriter to
-     * <code>true</code>.
+     * Closes this print writer. Flushes this writer and then closes the target.
+     * If an I/O error occurs, this writer's error flag is set to {@code true}.
      */
     @Override
     public void close() {
@@ -223,9 +248,9 @@
     }
 
     /**
-     * Flush this PrintWriter to ensure all pending data is sent out to the
-     * target Writer. This implementation flushes the target writer. If an error
-     * occurs, set an error in this PrintWriter to <code>true</code>.
+     * Ensures that all pending data is sent out to the target. It also
+     * flushes the target. If an I/O error occurs, this writer's error
+     * state is set to {@code true}.
      */
     @Override
     public void flush() {
@@ -243,52 +268,50 @@
     }
 
     /**
-     * Writes a string formatted by an intermediate <code>Formatter</code> to
-     * this writer using the given format string and arguments. A call to this
-     * method flushes the buffered output, if the automatic flushing is enabled.
-     * <p>
-     * The method uses the default for the current JVM instance locale, as if it
-     * is specified by the <code>Locale.getDefault()</code> call.
+     * Writes a string formatted by an intermediate {@code Formatter} to the
+     * target using the specified format string and arguments. For the locale,
+     * the default value of the current virtual machine instance is used. If
+     * automatic flushing is enabled then the buffer is flushed as well.
      * 
      * @param format
-     *            A format string.
+     *            the format string used for {@link java.util.Formatter#format}.
      * @param args
-     *            The arguments list. If there are more arguments than those
-     *            specified by the format string, then the additional arguments
-     *            are ignored.
-     * @return This writer.
+     *            the list of arguments passed to the formatter. If there are
+     *            more arguments than required by the {@code format} string,
+     *            then the additional arguments are ignored.
+     * @return this writer.
      * @throws IllegalFormatException
-     *             If the format string is illegal or incompatible with the
-     *             arguments or the arguments are less than those required by
-     *             the format string or any other illegal situation.
+     *             if the format string is illegal or incompatible with the
+     *             arguments, if there are not enough arguments or if any other
+     *             error regarding the format string or arguments is detected.
      * @throws NullPointerException
-     *             If the given format is null.
+     *             if {@code format} is {@code null}.
      */
     public PrintWriter format(String format, Object... args) {
         return format(Locale.getDefault(), format, args);
     }
 
     /**
-     * Writes a string formatted by an intermediate <code>Formatter</code> to
-     * this writer using the given format string and arguments. A call to this
-     * method flushes the buffered output, if the automatic flushing is enabled.
+     * Writes a string formatted by an intermediate {@code Formatter} to the
+     * target using the specified locale, format string and arguments. If
+     * automatic flushing is enabled then this writer is flushed.
      * 
      * @param l
-     *            The locale used in the method. If locale is null, then no
-     *            localization will be applied.
+     *            the locale used in the method. No localization will be applied
+     *            if {@code l} is {@code null}.
      * @param format
-     *            A format string.
+     *            the format string used for {@link java.util.Formatter#format}.
      * @param args
-     *            The arguments list. If there are more arguments than those
-     *            specified by the format string, then the additional arguments
-     *            are ignored.
-     * @return This writer.
+     *            the list of arguments passed to the formatter. If there are
+     *            more arguments than required by the {@code format} string,
+     *            then the additional arguments are ignored.
+     * @return this writer.
      * @throws IllegalFormatException
-     *             If the format string is illegal or incompatible with the
-     *             arguments or the arguments are less than those required by
-     *             the format string or any other illegal situation.
+     *             if the format string is illegal or incompatible with the
+     *             arguments, if there are not enough arguments or if any other
+     *             error regarding the format string or arguments is detected.
      * @throws NullPointerException
-     *             If the given format is null.
+     *             if {@code format} is {@code null}.
      */
     public PrintWriter format(Locale l, String format, Object... args) {
         if (format == null) {
@@ -303,25 +326,22 @@
 
     /**
      * Prints a formatted string. The behavior of this method is the same as
-     * this writer's <code>format(String format, Object... args)</code>
-     * method.
-     * <p>
-     * The method uses the default for the current JVM instance locale, as if it
-     * is specified by the <code>Locale.getDefault()</code> call.
+     * this writer's {@code #format(String, Object...)} method. For the locale,
+     * the default value of the current virtual machine instance is used.
      * 
      * @param format
-     *            A format string.
+     *            the format string used for {@link java.util.Formatter#format}.
      * @param args
-     *            The arguments list. If there are more arguments than those
-     *            specified by the format string, then the additional arguments
-     *            are ignored.
-     * @return This writer.
+     *            the list of arguments passed to the formatter. If there are
+     *            more arguments than required by the {@code format} string,
+     *            then the additional arguments are ignored.
+     * @return this writer.
      * @throws IllegalFormatException
-     *             If the format string is illegal or incompatible with the
-     *             arguments or the arguments are less than those required by
-     *             the format string or any other illegal situation.
+     *             if the format string is illegal or incompatible with the
+     *             arguments, if there are not enough arguments or if any other
+     *             error regarding the format string or arguments is detected.
      * @throws NullPointerException
-     *             If the given format is null.
+     *             if {@code format} is {@code null}.
      */
     public PrintWriter printf(String format, Object... args) {
         return format(format, args);
@@ -329,25 +349,24 @@
 
     /**
      * Prints a formatted string. The behavior of this method is the same as
-     * this writer's
-     * <code>format(Locale l, String format, Object... args)</code> method.
+     * this writer's {@code #format(Locale, String, Object...)} method.
      * 
      * @param l
-     *            The locale used in the method. If locale is null, then no
-     *            localization will be applied.
+     *            the locale used in the method. No localization will be applied
+     *            if {@code l} is {@code null}.
      * @param format
-     *            A format string.
+     *            the format string used for {@link java.util.Formatter#format}.
      * @param args
-     *            The arguments list. If there are more arguments than those
-     *            specified by the format string, then the additional arguments
-     *            are ignored.
-     * @return the PrintWriter.
+     *            the list of arguments passed to the formatter. If there are
+     *            more arguments than required by the {@code format} string,
+     *            then the additional arguments are ignored.
+     * @return this writer.
      * @throws IllegalFormatException
-     *             If the format string is illegal or incompatible with the
-     *             arguments or the arguments are less than those required by
-     *             the format string or any other illegal situation.
+     *             if the format string is illegal or incompatible with the
+     *             arguments, if there are not enough arguments or if any other
+     *             error regarding the format string or arguments is detected.
      * @throws NullPointerException
-     *             If the given format is null.
+     *             if {@code format} is {@code null}.
      */
     public PrintWriter printf(Locale l, String format, Object... args) {
         return format(l, format, args);
@@ -364,107 +383,114 @@
     }
 
     /**
-     * Prints the String representation of the character array parameter
-     * <code>charArray</code> to the target Writer.
+     * Prints the string representation of the specified character array
+     * to the target.
      * 
      * @param charArray
-     *            the character array to print on this Writer.
+     *            the character array to print to the target.
+     * @see #print(String)
      */
     public void print(char[] charArray) {
         print(new String(charArray, 0, charArray.length));
     }
 
     /**
-     * Prints the String representation of the character parameter
-     * <code>ch</code> to the target Writer.
+     * Prints the string representation of the specified character to the
+     * target.
      * 
      * @param ch
-     *            the character to print on this Writer.
+     *            the character to print to the target.
+     * @see #print(String)
      */
     public void print(char ch) {
         print(String.valueOf(ch));
     }
 
     /**
-     * Prints the String representation of the <code>double</code> parameter
-     * <code>dnum</code> to the target Writer.
+     * Prints the string representation of the specified double to the target.
      * 
      * @param dnum
-     *            the <code>double</code> to print on this Writer.
+     *            the double value to print to the target.
+     * @see #print(String)
      */
     public void print(double dnum) {
         print(String.valueOf(dnum));
     }
 
     /**
-     * Prints the String representation of the <code>float</code> parameter
-     * <code>fnum</code> to the target Writer.
+     * Prints the string representation of the specified float to the target.
      * 
      * @param fnum
-     *            the <code>float</code> to print on this Writer.
+     *            the float value to print to the target.
+     * @see #print(String)
      */
     public void print(float fnum) {
         print(String.valueOf(fnum));
     }
 
     /**
-     * Prints the String representation of the <code>int</code> parameter
-     * <code>inum</code> to the target Writer.
+     * Prints the string representation of the specified integer to the target.
      * 
      * @param inum
-     *            the <code>int</code> to print on this Writer.
+     *            the integer value to print to the target.
+     * @see #print(String)
      */
     public void print(int inum) {
         print(String.valueOf(inum));
     }
 
     /**
-     * Prints the String representation of the <code>long</code> parameter
-     * <code>lnum</code> to the target Writer.
+     * Prints the string representation of the specified long to the target.
      * 
      * @param lnum
-     *            the <code>long</code> to print on this Writer.
+     *            the long value to print to the target.
+     * @see #print(String)
      */
     public void print(long lnum) {
         print(String.valueOf(lnum));
     }
 
     /**
-     * Prints the String representation of the Object parameter <code>obj</code>
-     * to the target Writer.
+     * Prints the string representation of the specified object to the target.
      * 
      * @param obj
-     *            the Object to print on this Writer.
+     *            the object to print to the target.
+     * @see #print(String)
      */
     public void print(Object obj) {
         print(String.valueOf(obj));
     }
 
     /**
-     * Prints the String representation of the <code>String</code> parameter
-     * <code>str</code> to the target Writer.
-     * 
+     * Prints a string to the target. The string is converted to an array of
+     * bytes using the encoding chosen during the construction of this writer.
+     * The bytes are then written to the target with {@code write(int)}.
+     * <p>
+     * If an I/O error occurs, this writer's error flag is set to {@code true}.
+     *
      * @param str
-     *            the <code>String</code> to print on this Writer.
+     *            the string to print to the target.
+     * @see #write(int)
      */
     public void print(String str) {
         write(str != null ? str : String.valueOf((Object) null));
     }
 
     /**
-     * Prints the String representation of the <code>boolean</code> parameter
-     * <code>bool</code> to the target Writer.
+     * Prints the string representation of the specified boolean to the target.
      * 
      * @param bool
-     *            the <code>boolean</code> to print on this Writer.
+     *            the boolean value to print the target.
+     * @see #print(String)
      */
     public void print(boolean bool) {
         print(String.valueOf(bool));
     }
 
     /**
-     * Prints the String representation of the System property
-     * <code>"line.separator"</code> to the target Writer.
+     * Prints the string representation of the system property {@code
+     * "line.separator"} to the target. Flushes this writer if the autoflush
+     * flag is set to {@code true}.
      */
     public void println() {
         synchronized (lock) {
@@ -473,96 +499,108 @@
     }
 
     /**
-     * Prints the String representation of the character array parameter
-     * <code>charArray</code> to the target Writer followed by the System
-     * property <code>"line.separator"</code>.
+     * Prints the string representation of the specified character array
+     * followed by the system property {@code "line.separator"} to the target.
+     * Flushes this writer if the autoflush flag is set to {@code true}.
      * 
      * @param charArray
-     *            the character array to print on this Writer.
+     *            the character array to print to the target.
+     * @see #print(String)
      */
     public void println(char[] charArray) {
         println(new String(charArray, 0, charArray.length));
     }
 
     /**
-     * Prints the String representation of the character parameter
-     * <code>ch</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
+     * Prints the string representation of the specified character followed by
+     * the system property {@code "line.separator"} to the target. Flushes this
+     * writer if the autoflush flag is set to {@code true}.
      * 
      * @param ch
-     *            the character to print on this Writer.
+     *            the character to print to the target.
+     * @see #print(String)
      */
     public void println(char ch) {
         println(String.valueOf(ch));
     }
 
     /**
-     * Prints the String representation of the <code>double</code> parameter
-     * <code>dnum</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
+     * Prints the string representation of the specified double followed by the
+     * system property {@code "line.separator"} to the target. Flushes this
+     * writer if the autoflush flag is set to {@code true}.
      * 
      * @param dnum
-     *            the double to print on this Writer.
+     *            the double value to print to the target.
+     * @see #print(String)
      */
     public void println(double dnum) {
         println(String.valueOf(dnum));
     }
 
     /**
-     * Prints the String representation of the <code>float</code> parameter
-     * <code>fnum</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
+     * Prints the string representation of the specified float followed by the
+     * system property {@code "line.separator"} to the target. Flushes this
+     * writer if the autoflush flag is set to {@code true}.
      * 
      * @param fnum
-     *            the float to print on this Writer.
+     *            the float value to print to the target.
+     * @see #print(String)
      */
     public void println(float fnum) {
         println(String.valueOf(fnum));
     }
 
     /**
-     * Prints the String representation of the <code>int</code> parameter
-     * <code>inum</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
+     * Prints the string representation of the specified integer followed by the
+     * system property {@code "line.separator"} to the target. Flushes this
+     * writer if the autoflush flag is set to {@code true}.
      * 
      * @param inum
-     *            the int to print on this Writer.
+     *            the integer value to print to the target.
+     * @see #print(String)
      */
     public void println(int inum) {
         println(String.valueOf(inum));
     }
 
     /**
-     * Prints the String representation of the <code>long</code> parameter
-     * <code>lnum</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
+     * Prints the string representation of the specified long followed by the
+     * system property {@code "line.separator"} to the target. Flushes this
+     * writer if the autoflush flag is set to {@code true}.
      * 
      * @param lnum
-     *            the long to print on this Writer.
+     *            the long value to print to the target.
+     * @see #print(String)
      */
     public void println(long lnum) {
         println(String.valueOf(lnum));
     }
 
     /**
-     * Prints the String representation of the <code>Object</code> parameter
-     * <code>obj</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
+     * Prints the string representation of the specified object followed by the
+     * system property {@code "line.separator"} to the target. Flushes this
+     * writer if the autoflush flag is set to {@code true}.
      * 
      * @param obj
-     *            the <code>Object</code> to print on this Writer.
+     *            the object to print to the target.
+     * @see #print(String)
      */
     public void println(Object obj) {
         println(String.valueOf(obj));
     }
 
     /**
-     * Prints the String representation of the <code>String</code> parameter
-     * <code>str</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
-     * 
+     * Prints a string followed by the system property {@code "line.separator"}
+     * to the target. The string is converted to an array of bytes using the
+     * encoding chosen during the construction of this writer. The bytes are
+     * then written to the target with {@code write(int)}. Finally, this writer
+     * is flushed if the autoflush flag is set to {@code true}.
+     * <p>
+     * If an I/O error occurs, this writer's error flag is set to {@code true}.
+     *
      * @param str
-     *            the <code>String</code> to print on this Writer.
+     *            the string to print to the target.
+     * @see #write(int)
      */
     public void println(String str) {
         synchronized (lock) {
@@ -572,20 +610,20 @@
     }
 
     /**
-     * Prints the String representation of the <code>boolean</code> parameter
-     * <code>bool</code> to the target Writer followed by the System property
-     * <code>"line.separator"</code>.
+     * Prints the string representation of the specified boolean followed by the
+     * system property {@code "line.separator"} to the target. Flushes this
+     * writer if the autoflush flag is set to {@code true}.
      * 
      * @param bool
-     *            the boolean to print on this Writer.
+     *            the boolean value to print to the target.
+     * @see #print(String)
      */
     public void println(boolean bool) {
         println(String.valueOf(bool));
     }
 
     /**
-     * Set the flag indicating that this PrintWriter has encountered an IO
-     * error.
+     * Sets the error flag of this writer to {@code true}.
      */
     protected void setError() {
         synchronized (lock) {
@@ -594,7 +632,7 @@
     }
 
     /**
-     * Writes the entire character buffer buf to this Writer.
+     * Writes the character buffer {@code buf} to the target.
      * 
      * @param buf
      *            the non-null array containing characters to write.
@@ -605,15 +643,21 @@
     }
 
     /**
-     * Writes <code>count</code> characters starting at <code>offset</code>
-     * in <code>buf<code>
-     * to this Writer.
-     *
-     * @param 		buf			the non-null array containing characters to write.
-     * @param 		offset 		offset in buf to retrieve characters
-     * @param 		count 		maximum number of characters to write
+     * Writes {@code count} characters from {@code buffer} starting at {@code
+     * offset} to the target.
+     * <p>
+     * This writer's error flag is set to {@code true} if this writer is closed
+     * or an I/O error occurs.
      *
-     * @throws		ArrayIndexOutOfBoundsException 	If offset or count are outside of bounds.
+     * @param buf
+     *            the buffer to write to the target.
+     * @param offset
+     *            the index of the first character in {@code buffer} to write.
+     * @param count
+     *            the number of characters in {@code buffer} to write.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the length of {@code buf}.
      */
     @Override
     public void write(char buf[], int offset, int count) {
@@ -621,11 +665,14 @@
     }
 
     /**
-     * Writes the specified character to this Writer. This implementation writes
-     * the low order two bytes to the target writer.
+     * Writes one character to the target. Only the two least significant bytes
+     * of the integer {@code oneChar} are written.
+     * <p>
+     * This writer's error flag is set to {@code true} if this writer is closed
+     * or an I/O error occurs.
      * 
      * @param oneChar
-     *            The character to write
+     *            the character to write to the target.
      */
     @Override
     public void write(int oneChar) {
@@ -647,10 +694,10 @@
     }
 
     /**
-     * Writes the characters from the String <code>str</code> to this Writer.
+     * Writes the characters from the specified string to the target.
      * 
      * @param str
-     *            the non-null String containing the characters to write.
+     *            the non-null string containing the characters to write.
      */
     @Override
     public void write(String str) {
@@ -658,18 +705,18 @@
     }
 
     /**
-     * Writes <code>count</code> characters from the String <code>str</code>
-     * starting at <code>offset</code> to this Writer.
+     * Writes {@code count} characters from {@code str} starting at {@code
+     * offset} to the target.
      * 
      * @param str
-     *            the non-null String containing the characters to write.
+     *            the non-null string containing the characters to write.
      * @param offset
-     *            where in <code>str</code> to get chars from.
+     *            the index of the first character in {@code str} to write.
      * @param count
-     *            how many characters to write.
-     * 
-     * @throws ArrayIndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *            the number of characters from {@code str} to write.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the length of {@code str}.
      */
     @Override
     public void write(String str, int offset, int count) {
@@ -677,14 +724,11 @@
     }
 
     /**
-     * Append a char <code>c</code>to the PrintWriter. The
-     * PrintWriter.append(<code>c</code>) works the same way as
-     * PrintWriter.write(<code>c</code>).
+     * Appends the character {@code c} to the target.
      * 
      * @param c
-     *            The character appended to the PrintWriter.
-     * @return The PrintWriter.
-     * @see Writer#append(char)
+     *            the character to append to the target.
+     * @return this writer.
      */
     @Override
     public PrintWriter append(char c) {
@@ -693,15 +737,14 @@
     }
 
     /**
-     * Append a CharSequence <code>csq</code> to the PrintWriter. The
-     * PrintWriter.append(<code>csq</code>) works the same way as
-     * PrintWriter.write(<code>csq</code>.toString()). If <code>csq</code>
-     * is null, then "null" will be substituted for <code>csq</code>
+     * Appends the character sequence {@code csq} to the target. This
+     * method works the same way as {@code PrintWriter.print(csq.toString())}.
+     * If {@code csq} is {@code null}, then the string "null" is written
+     * to the target.
      * 
      * @param csq
-     *            The CharSequence appended to the PrintWriter.
-     * @return The PrintWriter
-     * @see Writer#append(CharSequence)
+     *            the character sequence appended to the target.
+     * @return this writer.
      */
     @Override
     public PrintWriter append(CharSequence csq) {
@@ -714,27 +757,25 @@
     }
 
     /**
-     * Append a subsequence of a CharSequence <code>csq</code> to the
-     * PrintWriter. The first char and the last char of the subsequence is
-     * specified by the parameter <code>start</code> and <code>end</code>.
-     * The PrintWriter.append(<code>csq</code>) works the same way as
-     * PrintWriter.write(<code>csq</code>.subSequence(<code>start</code>,<code>end</code>).toString).If
-     * <code>csq</code> is null, then "null" will be substituted for
-     * <code>csq</code>.
+     * Appends a subsequence of the character sequence {@code csq} to the
+     * target. This method works the same way as {@code
+     * PrintWriter.print(csq.subsequence(start, end).toString())}. If {@code
+     * csq} is {@code null}, then the specified subsequence of the string "null"
+     * will be written to the target.
      * 
      * @param csq
-     *            The CharSequence appended to the PrintWriter.
+     *            the character sequence appended to the target.
      * @param start
-     *            The index of the first char in the CharSequence appended to
-     *            the PrintWriter.
+     *            the index of the first char in the character sequence appended
+     *            to the target.
      * @param end
-     *            The index of the char after the last one in the CharSequence
-     *            appended to the PrintWriter.
-     * @return The PrintWriter.
-     * @throws IndexOutOfBoundsException
-     *             If start is less than end, end is greater than the length of
-     *             the CharSequence, or start or end is negative.
-     * @see Writer#append(CharSequence, int, int)
+     *            the index of the character following the last character of the
+     *            subsequence appended to the target.
+     * @return this writer.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code start > end}, {@code start < 0}, {@code end < 0} or
+     *             either {@code start} or {@code end} are greater or equal than
+     *             the length of {@code csq}.
      */
     @Override
     public PrintWriter append(CharSequence csq, int start, int end) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackInputStream.java Fri May  1 08:08:59 2009
@@ -20,31 +20,32 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * PushbackInputStream is a filter class which allows bytes read to be pushed
- * back into the stream so that they can be reread. Parsers may find this
- * useful. There is a progammable limit to the number of bytes which may be
- * pushed back. If the buffer of pushed back bytes is empty, bytes are read from
- * the source input stream.
+ * Wraps an existing {@link InputStream} and adds functionality to "push back"
+ * bytes that have been read, so that they can be read again. Parsers may find
+ * this useful. The number of bytes which may be pushed back can be specified
+ * during construction. If the buffer of pushed back bytes is empty, bytes are
+ * read from the underlying input stream.
  */
 public class PushbackInputStream extends FilterInputStream {
     /**
-     * The <code>byte</code> array containing the bytes to read.
+     * The buffer that contains pushed-back bytes.
      */
     protected byte[] buf;
 
     /**
-     * The current position within the byte array <code>buf</code>. A value
-     * equal to buf.length indicates no bytes available. A value of 0 indicates
-     * the buffer is full.
+     * The current position within {@code buf}. A value equal to
+     * {@code buf.length} indicates that no bytes are available. A value of 0
+     * indicates that the buffer is full.
      */
     protected int pos;
 
     /**
-     * Constructs a new PushbackInputStream on the InputStream <code>in</code>.
-     * The size of the pushback buffer is set to the default, or 1 byte.
+     * Constructs a new {@code PushbackInputStream} with the specified input
+     * stream as source. The size of the pushback buffer is set to the default
+     * value of 1 byte.
      * 
      * @param in
-     *            the InputStream to allow pushback operations on.
+     *            the source input stream.
      */
     public PushbackInputStream(InputStream in) {
         super(in);
@@ -53,13 +54,15 @@
     }
 
     /**
-     * Constructs a new PushbackInputStream on the InputStream <code>in</code>.
-     * The size of the pushback buffer is set to <code>size</code>.
+     * Constructs a new {@code PushbackInputStream} with {@code in} as source
+     * input stream. The size of the pushback buffer is set to {@code size}.
      * 
      * @param in
-     *            the InputStream to allow pushback operations on.
+     *            the source input stream.
      * @param size
-     *            the size of the pushback buffer (<code>size>=0</code>).
+     *            the size of the pushback buffer.
+     * @throws IllegalArgumentException
+     *             if {@code size} is negative.
      */
     public PushbackInputStream(InputStream in, int size) {
         super(in);
@@ -71,15 +74,14 @@
     }
 
     /**
-     * Answers a int representing then number of bytes that are available before
-     * this PushbackInputStream will block. This method returns the number of
-     * bytes available in the pushback buffer plus those available in the target
-     * stream.
-     * 
-     * @return int the number of bytes available before blocking.
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs in this stream.
+     * Returns the number of bytes that are available before this stream will
+     * block. This is the sum of the bytes available in the pushback buffer and
+     * those available from the source stream.
+     *
+     * @return the number of bytes available before blocking.
+     * @throws IOException
+     *             if this stream is closed or an I/O error occurs in the source
+     *             stream.
      */
     @Override
     public int available() throws IOException {
@@ -90,11 +92,11 @@
     }
 
     /**
-     * Close this PushbackInputStream. This implementation closes the target
-     * stream.
-     * 
+     * Closes this stream. This implementation closes the source stream
+     * and releases the pushback buffer.
+     *
      * @throws IOException
-     *             If an error occurs attempting to close this stream.
+     *             if an error occurs while closing this stream.
      */
     @Override
     public void close() throws IOException {
@@ -106,12 +108,13 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this PushbackInputStream
-     * supports mark() and reset(). This implementation always answers false
-     * since PushbackInputStreams do not support mark/reset.
-     * 
-     * @return boolean indicates whether or not mark() and reset() are
-     *         supported.
+     * Indicates whether this stream supports the {@code mark(int)} and
+     * {@code reset()} methods. {@code PushbackInputStream} does not support
+     * them, so it returns {@code false}.
+     * 
+     * @return always {@code false}.
+     * @see #mark(int)
+     * @see #reset()
      */
     @Override
     public boolean markSupported() {
@@ -119,15 +122,17 @@
     }
 
     /**
-     * Reads a single byte from this PushbackInputStream and returns the result
-     * as an int. The low-order byte is returned or -1 of the end of stream was
-     * encountered. If the pushback buffer does not contain any available bytes
-     * then a byte from the target input stream is returned.
-     * 
-     * @return int The byte read or -1 if end of stream.
-     * 
+     * Reads a single byte from this stream and returns it as an integer in the
+     * range from 0 to 255. If the pushback buffer does not contain any
+     * available bytes then a byte from the source input stream is returned.
+     * Blocks until one byte has been read, the end of the source stream is
+     * detected or an exception is thrown.
+     *
+     * @return the byte read or -1 if the end of the source stream has been
+     *         reached.
      * @throws IOException
-     *             If an IOException occurs.
+     *             if this stream is closed or an I/O error occurs while reading
+     *             from this stream.
      */
     @Override
     public int read() throws IOException {
@@ -144,23 +149,30 @@
     }
 
     /**
-     * Reads at most <code>length</code> bytes from this PushbackInputStream
-     * and stores them in byte array <code>buffer</code> starting at
-     * <code>offset</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of stream was encountered. This implementation
-     * reads bytes from the pushback buffer first, then the target stream if
-     * more bytes are required to satisfy <code>count</code>.
+     * Reads at most {@code length} bytes from this stream and stores them in
+     * the byte array {@code buffer} starting at {@code offset}. Bytes are read
+     * from the pushback buffer first, then from the source stream if more bytes
+     * are required. Blocks until {@code count} bytes have been read, the end of
+     * the source stream is detected or an exception is thrown.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
+     *            the array in which to store the bytes read from this stream.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read bytes.
+     *            the initial position in {@code buffer} to store the bytes read
+     *            from this stream.
      * @param length
-     *            the maximum number of bytes to store in <code>buffer</code>.
-     * @return the number of bytes actually read or -1 if end of stream.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes read or -1 if the end of the source stream
+     *         has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code buffer}.
      * @throws IOException
-     *             If an IOException occurs.
+     *             if this stream is closed or another I/O error occurs while
+     *             reading from this stream.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
      */
     @Override
     public int read(byte[] buffer, int offset, int length) throws IOException {
@@ -202,19 +214,14 @@
     }
 
     /**
-     * Skips <code>count</code> number of bytes in this PushbackInputStream.
-     * Subsequent <code>read()</code>'s will not return these bytes unless
-     * <code>reset()</code> is used. This implementation skips
-     * <code>count</code> number of bytes in the buffer and/or the target
-     * stream.
+     * Skips {@code count} bytes in this stream. This implementation skips bytes
+     * in the pushback buffer first and then in the source stream if necessary.
      * 
      * @param count
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
-     * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     @Override
     public long skip(long count) throws IOException {
@@ -236,39 +243,50 @@
     }
 
     /**
-     * Push back all the bytes in <code>buffer</code>. The bytes are pushed
-     * so that they would be read back buffer[0], buffer[1], etc. If the push
-     * back buffer cannot handle the entire contents of <code>buffer</code>,
-     * an IOException will be thrown. Some of the buffer may already be in the
-     * buffer after the exception is thrown.
-     * 
+     * Pushes all the bytes in {@code buffer} back to this stream. The bytes are
+     * pushed back in such a way that the next byte read from this stream is
+     * buffer[0], then buffer[1] and so on.
+     * <p>
+     * If this stream's internal pushback buffer cannot store the entire
+     * contents of {@code buffer}, an {@code IOException} is thrown. Parts of
+     * {@code buffer} may have already been copied to the pushback buffer when
+     * the exception is thrown.
+     *
      * @param buffer
-     *            the byte array containing bytes to push back into the stream.
-     * 
+     *            the buffer containing the bytes to push back to this stream.
      * @throws IOException
-     *             If the pushback buffer becomes, or is, full.
+     *             if the free space in the internal pushback buffer is not
+     *             sufficient to store the contents of {@code buffer}.
      */
     public void unread(byte[] buffer) throws IOException {
         unread(buffer, 0, buffer.length);
     }
 
     /**
-     * Push back <code>length</code> number of bytes in <code>buffer</code>
-     * starting at <code>offset</code>. The bytes are pushed so that they
-     * would be read back buffer[offset], buffer[offset+1], etc. If the push
-     * back buffer cannot handle the bytes copied from <code>buffer</code>,
-     * an IOException will be thrown. Some of the bytes may already be in the
-     * buffer after the exception is thrown.
+     * Pushes a subset of the bytes in {@code buffer} back to this stream. The
+     * subset is defined by the start position {@code offset} within
+     * {@code buffer} and the number of bytes specified by {@code length}. The
+     * bytes are pushed back in such a way that the next byte read from this
+     * stream is {@code buffer[offset]}, then {@code buffer[1]} and so on.
+     * <p>
+     * If this stream's internal pushback buffer cannot store the selected
+     * subset of {@code buffer}, an {@code IOException} is thrown. Parts of
+     * {@code buffer} may have already been copied to the pushback buffer when
+     * the exception is thrown.
      * 
      * @param buffer
-     *            the byte array containing bytes to push back into the stream.
+     *            the buffer containing the bytes to push back to this stream.
      * @param offset
-     *            the location to start taking bytes to push back.
+     *            the index of the first byte in {@code buffer} to push back.
      * @param length
      *            the number of bytes to push back.
-     * 
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code buffer}.
      * @throws IOException
-     *             If the pushback buffer becomes, or is, full.
+     *             if the free space in the internal pushback buffer is not
+     *             sufficient to store the selected contents of {@code buffer}.
      */
     public void unread(byte[] buffer, int offset, int length)
             throws IOException {
@@ -288,15 +306,19 @@
     }
 
     /**
-     * Push back one <code>byte</code>. Takes the byte <code>oneByte</code>
-     * and puts in in the local buffer of bytes to read back before accessing
-     * the target input stream.
-     * 
+     * Pushes the specified byte {@code oneByte} back to this stream. Only the
+     * least significant byte of the integer {@code oneByte} is pushed back.
+     * This is done in such a way that the next byte read from this stream is
+     * {@code (byte) oneByte}.
+     * <p>
+     * If this stream's internal pushback buffer cannot store the byte, an
+     * {@code IOException} is thrown.
+     *
      * @param oneByte
-     *            the byte to push back into the stream.
-     * 
+     *            the byte to push back to this stream.
      * @throws IOException
-     *             If the pushback buffer is already full.
+     *             if this stream is closed or the internal pushback buffer is
+     *             full.
      */
     public void unread(int oneByte) throws IOException {
         if (buf == null) {
@@ -309,13 +331,12 @@
     }
 
     /**
-     * Make a mark of the current position in the stream but the mark method
-     * does nothing.
+     * Marks the current position in this stream. Setting a mark is not
+     * supported in this class; this implementation does nothing.
      * 
      * @param readlimit
-     *            the maximum number of bytes that are able to be read before
-     *            the mark becomes invalid
-     * @see FilterInputStream#mark(int)
+     *            the number of bytes that can be read from this stream before
+     *            the mark is invalidated; this parameter is ignored.
      */
     @Override
     public void mark(int readlimit) {
@@ -323,12 +344,12 @@
     }
 
     /**
-     * Reset current position to the mark made previously int the stream, but
-     * the reset method will throw IOException and do nothing else if called.
+     * Resets this stream to the last marked position. Resetting the stream is
+     * not supported in this class; this implementation always throws an
+     * {@code IOException}.
      * 
      * @throws IOException
-     *             If the method is called
-     * @see FilterInputStream#reset()
+     *             if this method is called.
      */
     @Override
     public void reset() throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackReader.java Fri May  1 08:08:59 2009
@@ -20,33 +20,32 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * PushbackReader is a filter class which allows chars read to be pushed back
- * into the stream so that they can be reread. Parsers may find this useful.
- * There is a progammable limit to the number of chars which may be pushed back.
- * If the buffer of pushed back chars is empty, chars are read from the source
- * reader.
- * 
+ * Wraps an existing {@link Reader} and adds functionality to "push back"
+ * characters that have been read, so that they can be read again. Parsers may
+ * find this useful. The number of characters which may be pushed back can be
+ * specified during construction. If the buffer of pushed back bytes is empty,
+ * characters are read from the underlying reader.
  */
 public class PushbackReader extends FilterReader {
     /**
-     * The <code>char</code> array containing the chars to read.
+     * The {@code char} array containing the chars to read.
      */
     char[] buf;
 
     /**
-     * The current position within the char array <code>buf</code>. A value
+     * The current position within the char array {@code buf}. A value
      * equal to buf.length indicates no chars available. A value of 0 indicates
      * the buffer is full.
      */
     int pos;
 
     /**
-     * Constructs a new PushbackReader on the Reader <code>in</code>. The
-     * size of the pushback buffer is set to the default, or 1 character.
+     * Constructs a new {@code PushbackReader} with the specified reader as
+     * source. The size of the pushback buffer is set to the default value of 1
+     * character.
      * 
      * @param in
-     *            the Reader to allow pushback operations on.
-     * 
+     *            the source reader.
      */
     public PushbackReader(Reader in) {
         super(in);
@@ -55,16 +54,15 @@
     }
 
     /**
-     * Constructs a new PushbackReader on the Reader <code>in</code>. The
-     * size of the pushback buffer is set to <code>size</code> characters.
+     * Constructs a new {@code PushbackReader} with {@code in} as source reader.
+     * The size of the pushback buffer is set to {@code size}.
      * 
      * @param in
-     *            the Reader to allow pushback operations on.
+     *            the source reader.
      * @param size
-     *            the size of the pushback buffer (<code>size>=0</code>) in
-     *            characters.
+     *            the size of the pushback buffer.
      * @throws IllegalArgumentException
-     *             if size <= 0
+     *             if {@code size} is negative.
      */
     public PushbackReader(Reader in, int size) {
         super(in);
@@ -76,12 +74,11 @@
     }
 
     /**
-     * Close this PushbackReader. This implementation closes this reader,
-     * releases the buffer used to pushback characters, and closes the target
-     * reader.
+     * Closes this reader. This implementation closes the source reader
+     * and releases the pushback buffer.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this Reader.
+     *             if an error occurs while closing this reader.
      */
     @Override
     public void close() throws IOException {
@@ -92,14 +89,15 @@
     }
 
     /**
-     * Mark this PushbackReader. Since mark is not supported, this method will
-     * always throw IOException.
+     * Marks the current position in this stream. Setting a mark is not
+     * supported in this class; this implementation always throws an
+     * {@code IOException}.
      * 
      * @param readAheadLimit
-     *            ignored, this method always throws IOException.
-     * 
+     *            the number of character that can be read from this reader
+     *            before the mark is invalidated; this parameter is ignored.
      * @throws IOException
-     *             Since mark is not supported byt PushbackReader.
+     *             if this method is called.
      */
     @Override
     public void mark(int readAheadLimit) throws IOException {
@@ -107,12 +105,13 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this PushbackReader supports
-     * mark() and reset(). This implementation always answers false since
-     * PushbackReaders do not support mark/reset.
-     * 
-     * @return boolean indicates whether or not mark() and reset() are
-     *         supported.
+     * Indicates whether this reader supports the {@code mark(int)} and
+     * {@code reset()} methods. {@code PushbackReader} does not support them, so
+     * it returns {@code false}.
+     * 
+     * @return always {@code false}.
+     * @see #mark(int)
+     * @see #reset()
      */
     @Override
     public boolean markSupported() {
@@ -120,15 +119,18 @@
     }
 
     /**
-     * Reads a single character from this PushbackReader and returns the result
-     * as an int. The 2 lowest-order bytes are returned or -1 of the end of
-     * stream was encountered. If the pushback buffer does not contain any
-     * available chars then a char from the target input reader is returned.
-     * 
-     * @return int The char read or -1 if end of stream.
-     * 
+     * Reads a single character from this reader and returns it as an integer
+     * with the two higher-order bytes set to 0. Returns -1 if the end of the
+     * reader has been reached. If the pushback buffer does not contain any
+     * available characters then a character from the source reader is returned.
+     * Blocks until one character has been read, the end of the source reader is
+     * detected or an exception is thrown.
+     *
+     * @return the character read or -1 if the end of the source reader has been
+     *         reached.
      * @throws IOException
-     *             If an IOException occurs.
+     *             if this reader is closed or an I/O error occurs while reading
+     *             from this reader.
      */
     @Override
     public int read() throws IOException {
@@ -149,23 +151,29 @@
     }
 
     /**
-     * Reads at most <code>count</code> chars from this PushbackReader and
-     * stores them in char array <code>buffer</code> starting at
-     * <code>offset</code>. Answer the number of chars actually read or -1 if
-     * no chars were read and end of stream was encountered. This implementation
-     * reads chars from the pushback buffer first, then the target stream if
-     * more chars are required to satisfy <code>count</code>.
+     * Reads at most {@code length} bytes from this reader and stores them in
+     * byte array {@code buffer} starting at {@code offset}. Characters are
+     * read from the pushback buffer first, then from the source reader if more
+     * bytes are required. Blocks until {@code count} characters have been read,
+     * the end of the source reader is detected or an exception is thrown.
      * 
      * @param buffer
-     *            the char array in which to store the read chars.
+     *            the array in which to store the characters read from this
+     *            reader.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read chars.
+     *            the initial position in {@code buffer} to store the characters
+     *            read from this reader.
      * @param count
-     *            the maximum number of chars to store in <code>buffer</code>.
-     * @return the number of chars actually read or -1 if end of stream.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes read or -1 if the end of the source reader
+     *         has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if
+     *             {@code offset + count} is greater than the length of
+     *             {@code buffer}.
      * @throws IOException
-     *             If an IOException occurs.
+     *             if this reader is closed or another I/O error occurs while
+     *             reading from this reader.
      */
     @Override
     public int read(char[] buffer, int offset, int count) throws IOException {
@@ -207,19 +215,17 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether or not this
-     * PushbackReader is ready to be read without blocking. If the result is
-     * <code>true</code>, the next <code>read()</code> will not block. If
-     * the result is <code>false</code> this Reader may or may not block when
-     * <code>read()</code> is sent.
+     * Indicates whether this reader is ready to be read without blocking.
+     * Returns {@code true} if this reader will not block when {@code read} is
+     * called, {@code false} if unknown or blocking will occur.
      * 
-     * @return boolean <code>true</code> if the receiver will not block when
-     *         <code>read()</code> is called, <code>false</code> if unknown
+     * @return {@code true} if the receiver will not block when
+     *         {@code read()} is called, {@code false} if unknown
      *         or blocking will occur.
-     * 
      * @throws IOException
-     *             If the Reader is already closed or some other IO error
-     *             occurs.
+     *             if this reader is closed or some other I/O error occurs.
+     * @see #read()
+     * @see #read(char[], int, int)
      */
     @Override
     public boolean ready() throws IOException {
@@ -232,11 +238,12 @@
     }
 
     /**
-     * Resets this PushbackReader. Since mark is not supported, always throw
-     * IOException.
+     * Resets this reader to the last marked position. Resetting the reader is
+     * not supported in this class; this implementation always throws an
+     * {@code IOException}.
      * 
      * @throws IOException
-     *             Since mark is not supported.
+     *             if this method is called.
      */
     @Override
     public void reset() throws IOException {
@@ -244,39 +251,56 @@
     }
 
     /**
-     * Push back all the chars in <code>buffer</code>. The chars are pushed
-     * so that they would be read back buffer[0], buffer[1], etc. If the push
-     * back buffer cannot handle the entire contents of <code>buffer</code>,
-     * an IOException will be thrown. Some of the buffer may already be in the
-     * buffer after the exception is thrown.
-     * 
+     * Pushes all the characters in {@code buffer} back to this reader. The
+     * characters are pushed back in such a way that the next character read
+     * from this reader is buffer[0], then buffer[1] and so on.
+     * <p>
+     * If this reader's internal pushback buffer cannot store the entire
+     * contents of {@code buffer}, an {@code IOException} is thrown. Parts of
+     * {@code buffer} may have already been copied to the pushback buffer when
+     * the exception is thrown.
+     *
      * @param buffer
-     *            the char array containing chars to push back into the reader.
-     * 
+     *            the buffer containing the characters to push back to this
+     *            reader.
      * @throws IOException
-     *             If the pushback buffer becomes, or is, full.
+     *             if this reader is closed or the free space in the internal
+     *             pushback buffer is not sufficient to store the contents of
+     *             {@code buffer}.
      */
     public void unread(char[] buffer) throws IOException {
         unread(buffer, 0, buffer.length);
     }
 
     /**
-     * Push back <code>count</code> number of chars in <code>buffer</code>
-     * starting at <code>offset</code>. The chars are pushed so that they
-     * would be read back buffer[offset], buffer[offset+1], etc. If the push
-     * back buffer cannot handle the chars copied from <code>buffer</code>,
-     * an IOException will be thrown. Some of the chars may already be in the
-     * buffer after the exception is thrown.
-     * 
+     * Pushes a subset of the characters in {@code buffer} back to this reader.
+     * The subset is defined by the start position {@code offset} within
+     * {@code buffer} and the number of characters specified by {@code length}.
+     * The bytes are pushed back in such a way that the next byte read from this
+     * stream is {@code buffer[offset]}, then {@code buffer[1]} and so on.
+     * <p>
+     * If this stream's internal pushback buffer cannot store the selected
+     * subset of {@code buffer}, an {@code IOException} is thrown. Parts of
+     * {@code buffer} may have already been copied to the pushback buffer when
+     * the exception is thrown.
+     *
      * @param buffer
-     *            the char array containing chars to push back into the reader.
+     *            the buffer containing the characters to push back to this
+     *            reader.
      * @param offset
-     *            the location to start taking chars to push back.
+     *            the index of the first byte in {@code buffer} to push back.
      * @param count
-     *            the number of chars to push back.
-     * 
+     *            the number of bytes to push back.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if
+     *             {@code offset + count} is greater than the length of
+     *             {@code buffer}.
      * @throws IOException
-     *             If the pushback buffer becomes, or is, full.
+     *             if this reader is closed or the free space in the internal
+     *             pushback buffer is not sufficient to store the selected
+     *             contents of {@code buffer}.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
      */
     public void unread(char[] buffer, int offset, int count) throws IOException {
         synchronized (lock) {
@@ -301,15 +325,18 @@
     }
 
     /**
-     * Push back one <code>char</code>. Takes the char <code>oneChar</code>
-     * and puts in in the local buffer of chars to read back before accessing
-     * the target input stream.
-     * 
+     * Pushes the specified character {@code oneChar} back to this reader. This
+     * is done in such a way that the next character read from this reader is
+     * {@code (char) oneChar}.
+     * <p>
+     * If this reader's internal pushback buffer cannot store the character, an
+     * {@code IOException} is thrown.
+     *
      * @param oneChar
-     *            the char to push back into the stream.
-     * 
+     *            the character to push back to this stream.
      * @throws IOException
-     *             If the pushback buffer is already full.
+     *             if this reader is closed or the internal pushback buffer is
+     *             full.
      */
     public void unread(int oneChar) throws IOException {
         synchronized (lock) {
@@ -324,19 +351,16 @@
     }
 
     /**
-     * Skips <code>count</code> number of characters in this Reader.
-     * Subsequent <code>read()</code>'s will not return these characters
-     * unless <code>reset()</code> is used.
+     * Skips {@code count} characters in this reader. This implementation skips
+     * characters in the pushback buffer first and then in the source reader if
+     * necessary.
      * 
      * @param count
-     *            the maximum number of characters to skip.
+     *            the number of characters to skip.
      * @return the number of characters actually skipped.
-     * 
+     * @throws IllegalArgumentException if {@code count < 0}.
      * @throws IOException
-     *             If the Reader is already closed or some other IO error
-     *             occurs.
-     * @throws IllegalArgumentException
-     *             If count is negative.
+     *             if this reader is closed or another I/O error occurs.
      */
     @Override
     public long skip(long count) throws IOException {



Mime
View raw message