harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [7/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/OutputStreamWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java Fri May  1 08:08:59 2009
@@ -30,15 +30,15 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * OutputStreamWriter is a class for turning a character output stream into a
- * byte output stream. The conversion of Unicode characters to their byte
- * equivalents is determined by the converter used. By default, the encoding is
- * ISO8859_1 (ISO-Latin-1) but can be changed by calling the constructor which
- * takes an encoding.
+ * A class for turning a character stream into a byte stream. Data written to
+ * the target input stream is converted into bytes by either a default or a
+ * provided character converter. The default encoding is taken from the
+ * "file.encoding" system property. {@code OutputStreamWriter} contains a buffer
+ * of bytes to be written to target stream and converts these into characters as
+ * needed. The buffer size is 8K.
  * 
  * @see InputStreamReader
  */
-
 public class OutputStreamWriter extends Writer {
 
     private OutputStream out;
@@ -48,12 +48,12 @@
     private ByteBuffer bytes = ByteBuffer.allocate(8192);
 
     /**
-     * Constructs a new OutputStreamWriter using <code>out</code> as the
-     * OutputStream to write converted characters to. The default character
-     * encoding is used (see class description).
+     * Constructs a new OutputStreamWriter using {@code out} as the target
+     * stream to write converted characters to. The default character encoding
+     * is used.
      * 
      * @param out
-     *            the non-null OutputStream to write converted bytes to.
+     *            the non-null target stream to write converted bytes to.
      */
     public OutputStreamWriter(OutputStream out) {
         super(out);
@@ -67,18 +67,19 @@
     }
 
     /**
-     * Constructs a new OutputStreamWriter using <code>out</code> as the
-     * OutputStream to write converted characters to and <code>enc</code> as
-     * the character encoding. If the encoding cannot be found, an
+     * Constructs a new OutputStreamWriter using {@code out} as the target
+     * stream to write converted characters to and {@code enc} as the character
+     * encoding. If the encoding cannot be found, an
      * UnsupportedEncodingException error is thrown.
      * 
      * @param out
-     *            the non-null OutputStream to write converted bytes to.
+     *            the target stream to write converted bytes to.
      * @param enc
-     *            the non-null String describing the desired character encoding.
-     * 
+     *            the string describing the desired character encoding.
+     * @throws NullPointerException
+     *             if {@code enc} is {@code null}.
      * @throws UnsupportedEncodingException
-     *             if the encoding cannot be found.
+     *             if the encoding specified by {@code enc} cannot be found.
      */
     public OutputStreamWriter(OutputStream out, final String enc)
             throws UnsupportedEncodingException {
@@ -97,15 +98,14 @@
     }
 
     /**
-     * Constructs a new OutputStreamWriter using <code>out</code> as the
-     * OutputStream to write converted characters to and <code>cs</code> as
-     * the character encoding.
-     * 
+     * Constructs a new OutputStreamWriter using {@code out} as the target
+     * stream to write converted characters to and {@code cs} as the character
+     * encoding.
      * 
      * @param out
-     *            the non-null OutputStream to write converted bytes to.
+     *            the target stream to write converted bytes to.
      * @param cs
-     *            the non-null Charset which specify the character encoding.
+     *            the {@code Charset} that specifies the character encoding.
      */
     public OutputStreamWriter(OutputStream out, Charset cs) {
         super(out);
@@ -116,14 +116,14 @@
     }
 
     /**
-     * Constructs a new OutputStreamWriter using <code>out</code> as the
-     * OutputStream to write converted characters to and <code>enc</code> as
-     * the character encoding.
+     * Constructs a new OutputStreamWriter using {@code out} as the target
+     * stream to write converted characters to and {@code enc} as the character
+     * encoder.
      * 
      * @param out
-     *            the non-null OutputStream to write converted bytes to.
+     *            the target stream to write converted bytes to.
      * @param enc
-     *            the non-null CharsetEncoder which used to character encoding.
+     *            the character encoder used for character conversion.
      */
     public OutputStreamWriter(OutputStream out, CharsetEncoder enc) {
         super(out);
@@ -133,16 +133,15 @@
     }
 
     /**
-     * Close this OutputStreamWriter. This implementation first flushes the
-     * buffer and the target OutputStream. The OutputStream is then closed and
-     * the resources for the buffer and converter are freed.
+     * Closes this writer. This implementation flushes the buffer as well as the
+     * target stream. The target stream is then closed and the resources for the
+     * buffer and converter are released.
      * <p>
      * Only the first invocation of this method has any effect. Subsequent calls
-     * do no work.
+     * do nothing.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this
-     *             OutputStreamWriter.
+     *             if an error occurs while closing this writer.
      */
     @Override
     public void close() throws IOException {
@@ -159,13 +158,12 @@
     }
 
     /**
-     * Flush this OutputStreamWriter. This implementation ensures all buffered
-     * bytes are written to the target OutputStream. After writing the bytes,
-     * the target OutputStream is then flushed.
+     * Flushes this writer. This implementation ensures that all buffered bytes
+     * are written to the target stream. After writing the bytes, the target
+     * stream is flushed as well.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this
-     *             OutputStreamWriter.
+     *             if an error occurs while flushing this writer.
      */
     @Override
     public void flush() throws IOException {
@@ -189,14 +187,12 @@
     }
 
     /**
-     * Answer the String which identifies the encoding used to convert
-     * characters to bytes. The value <code>null</code> is returned if this
-     * Writer has been closed.
+     * Gets the name of the encoding that is used to convert characters to
+     * bytes.
      * 
-     * @return the String describing the converter or null if this Writer is
-     *         closed.
+     * @return the string describing the converter or {@code null} if this
+     *         writer is closed.
      */
-
     public String getEncoding() {
         if (encoder == null) {
             return null;
@@ -205,24 +201,24 @@
     }
 
     /**
-     * Writes <code>count</code> characters starting at <code>offset</code>
-     * in <code>buf</code> to this Writer. The characters are immediately
-     * converted to bytes by the character converter and stored in a local
-     * buffer. If the buffer becomes full as a result of this write, this Writer
-     * is flushed.
+     * Writes {@code count} characters starting at {@code offset} in {@code buf}
+     * to this writer. The characters are immediately converted to bytes by the
+     * character converter and stored in a local buffer. If the buffer gets full
+     * as a result of the conversion, this writer is flushed.
      * 
      * @param buf
-     *            the non-null array containing characters to write.
+     *            the array containing characters to write.
      * @param offset
-     *            offset in buf to retrieve characters
+     *            the index of the first character in {@code buf} to write.
      * @param count
-     *            maximum number of characters to write
-     * 
-     * @throws IOException
-     *             If this OutputStreamWriter has already been closed or some
-     *             other IOException occurs.
+     *            the maximum number of characters to write.
      * @throws IndexOutOfBoundsException
-     *             If offset or count is outside of bounds.
+     *             if {@code offset < 0} or {@code count < 0}, or if
+     *             {@code offset + count} is greater than the size of
+     *             {@code buf}.
+     * @throws IOException
+     *             if this writer has already been closed or another I/O error
+     *             occurs.
      */
     @Override
     public void write(char[] buf, int offset, int count) throws IOException {
@@ -252,17 +248,15 @@
     }
 
     /**
-     * Writes out the character <code>oneChar</code> to this Writer. The
-     * low-order 2 bytes are immediately converted to bytes by the character
-     * converter and stored in a local buffer. If the buffer becomes full as a
-     * result of this write, this Writer is flushed.
+     * Writes the character {@code oneChar} to this writer. The lowest two bytes
+     * of the integer {@code oneChar} are immediately converted to bytes by the
+     * character converter and stored in a local buffer. If the buffer gets full
+     * by converting this character, this writer is flushed.
      * 
      * @param oneChar
-     *            the character to write
-     * 
+     *            the character to write.
      * @throws IOException
-     *             If this OutputStreamWriter has already been closed or some
-     *             other IOException occurs.
+     *             if this writer is closed or another I/O error occurs.
      */
     @Override
     public void write(int oneChar) throws IOException {
@@ -274,26 +268,24 @@
     }
 
     /**
-     * Writes <code>count</code> characters starting at <code>offset</code>
-     * in <code>str</code> to this Writer. The characters are immediately
-     * converted to bytes by the character converter and stored in a local
-     * buffer. If the buffer becomes full as a result of this write, this Writer
-     * is flushed.
+     * Writes {@code count} characters starting at {@code offset} in {@code str}
+     * to this writer. The characters are immediately converted to bytes by the
+     * character converter and stored in a local buffer. If the buffer gets full
+     * as a result of the conversion, this writer is flushed.
      * 
      * @param str
-     *            the non-null String containing characters to write.
+     *            the string containing characters to write.
      * @param offset
-     *            offset in str to retrieve characters
+     *            the start position in {@code str} for retrieving characters.
      * @param count
-     *            maximum number of characters to write
-     * 
+     *            the maximum number of characters to write.
      * @throws IOException
-     *             If this OutputStreamWriter has already been closed or some
-     *             other IOException occurs.
+     *             if this writer has already been closed or another I/O error
+     *             occurs.
      * @throws IndexOutOfBoundsException
-     *             If count is negative
-     * @throws StringIndexOutOfBoundsException
-     *             If offset is negative or offset + count is outside of bounds
+     *             if {@code offset < 0} or {@code count < 0}, or if
+     *             {@code offset + count} is bigger than the length of
+     *             {@code str}.
      */
     @Override
     public void write(String str, int offset, int count) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java Fri May  1 08:08:59 2009
@@ -20,9 +20,9 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * PipedInputStream is a class which receives information on a communications
- * pipe. When two threads want to pass data back and forth, one creates a piped
- * output stream and the other creates a piped input stream.
+ * Receives information from a communications pipe. When two threads want to
+ * pass data back and forth, one creates a piped output stream and the other one
+ * creates a piped input stream.
  * 
  * @see PipedOutputStream
  */
@@ -38,58 +38,56 @@
     protected byte buffer[];
 
     /**
-     * The index in <code>buffer</code> where the next byte will be written.
+     * The index in {@code buffer} where the next byte will be written.
      */
     protected int in = -1;
 
     /**
-     * The index in <code>buffer</code> where the next byte will be read.
+     * The index in {@code buffer} where the next byte will be read.
      */
     protected int out = 0;
 
     /**
-     * The size of the default pipe in bytes
+     * The size of the default pipe in bytes.
      */
     protected static final int PIPE_SIZE = 1024;
 
     /**
-     * Indicates if this pipe is connected
+     * Indicates if this pipe is connected.
      */
     boolean isConnected = false;
 
     /**
-     * Constructs a new unconnected PipedInputStream. The resulting Stream must
-     * be connected to a PipedOutputStream before data may be read from it.
-     * 
+     * Constructs a new unconnected {@code PipedInputStream}. The resulting
+     * stream must be connected to a {@link PipedOutputStream} before data may
+     * be read from it.
      */
     public PipedInputStream() {
         /* empty */
     }
 
     /**
-     * Constructs a new PipedInputStream connected to the PipedOutputStream
-     * <code>out</code>. Any data written to the output stream can be read
-     * from the this input stream.
+     * Constructs a new {@code PipedInputStream} connected to the
+     * {@link PipedOutputStream} {@code out}. Any data written to the output
+     * stream can be read from the this input stream.
      * 
      * @param out
-     *            the PipedOutputStream to connect to.
-     * 
+     *            the piped output stream to connect to.
      * @throws IOException
-     *             if this or <code>out</code> are already connected.
+     *             if this stream or {@code out} are already connected.
      */
     public PipedInputStream(PipedOutputStream out) throws IOException {
         connect(out);
     }
 
     /**
-     * Answers a int representing the number of bytes that are available before
-     * this PipedInputStream will block. This method returns the number of bytes
-     * written to the pipe but not read yet up to the size of the pipe.
-     * 
-     * @return int the number of bytes available before blocking.
+     * Returns the number of bytes that are available before this stream will
+     * block. This implementation returns the number of bytes written to this
+     * pipe that have not been read yet.
      * 
+     * @return the number of bytes available before blocking.
      * @throws IOException
-     *             If an error occurs in this stream.
+     *             if an error occurs in this stream.
      */
     @Override
     public synchronized int available() throws IOException {
@@ -100,11 +98,11 @@
     }
 
     /**
-     * Close this PipedInputStream. This implementation releases the buffer used
-     * for the pipe and notifies all threads waiting to read or write.
+     * Closes this stream. This implementation releases the buffer used for the
+     * pipe and notifies all threads waiting to read or write.
      * 
      * @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 {
@@ -118,33 +116,36 @@
     }
 
     /**
-     * Connects this PipedInputStream to a PipedOutputStream. Any data written
-     * to the OutputStream becomes readable in this InputStream.
+     * Connects this {@code PipedInputStream} to a {@link PipedOutputStream}.
+     * Any data written to the output stream becomes readable in this input
+     * stream.
      * 
      * @param src
-     *            the source PipedOutputStream.
-     * 
+     *            the source output stream.
      * @throws IOException
-     *             If either stream is already connected.
+     *             if either stream is already connected.
      */
     public void connect(PipedOutputStream src) throws IOException {
         src.connect(this);
     }
 
     /**
-     * Reads a single byte from this PipedInputStream and returns the result as
-     * an int. The low-order byte is returned or -1 of the end of stream was
-     * encountered. If there is no data in the pipe, this method blocks until
-     * there is data available. Separate threads should be used for the reader
-     * of the PipedInputStream and the PipedOutputStream. There may be
-     * undesirable results if more than one Thread interacts a input or output
-     * pipe.
-     * 
-     * @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. Returns -1 if the end of this stream has been
+     * reached. If there is no data in the pipe, this method blocks until data
+     * is available, the end of the stream is detected or an exception is
+     * thrown.
+     * <p>
+     * Separate threads should be used to read from a {@code PipedInputStream}
+     * and to write to the connected {@link PipedOutputStream}. If the same
+     * thread is used, a deadlock may occur.
+     *
+     * @return the byte read or -1 if the end of the source stream has been
+     *         reached.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or not connected to an output
+     *             stream, or if the thread writing to the connected output
+     *             stream is no longer alive.
      */
     @Override
     public synchronized int read() throws IOException {
@@ -191,25 +192,35 @@
     }
 
     /**
-     * Reads at most <code>count</code> bytes from this PipedInputStream 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. Separate threads
-     * should be used for the reader of the PipedInputStream and the
-     * PipedOutputStream. There may be undesirable results if more than one
-     * Thread interacts a input or output pipe.
-     * 
+     * Reads at most {@code count} bytes from this stream and stores them in the
+     * byte array {@code bytes} starting at {@code offset}. Blocks until at
+     * least one byte has been read, the end of the stream is detected or an
+     * exception is thrown.
+     * <p>
+     * Separate threads should be used to read from a {@code PipedInputStream}
+     * and to write to the connected {@link PipedOutputStream}. If the same
+     * thread is used, a deadlock may occur.
+     *
      * @param bytes
-     *            the byte array in which to store the read bytes.
+     *            the array in which to store the bytes read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read bytes.
+     *            the initial position in {@code bytes} to store the bytes
+     *            read from this stream.
      * @param count
-     *            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 bytes}.
+     * @return the number of bytes actually read or -1 if the end of the stream
+     *         has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the size of {@code bytes}.
+     * @throws InterruptedIOException
+     *             if the thread reading from this stream is interrupted.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or not connected to an output
+     *             stream, or if the thread writing to the connected output
+     *             stream is no longer alive.
+     * @throws NullPointerException
+     *             if {@code bytes} is {@code null}.
      */
     @Override
     public synchronized int read(byte[] bytes, int offset, int count)
@@ -299,19 +310,21 @@
     }
 
     /**
-     * Receives a byte and stores it into the PipedInputStream. This called by
-     * PipedOutputStream.write() when writes occur. The lowest-order byte is
-     * stored at index <code>in</code> in the <code>buffer</code>.
-     * <P>
-     * If the buffer is full and the thread sending #receive is interrupted, the
-     * InterruptedIOException will be thrown.
+     * Receives a byte and stores it in this stream's {@code buffer}. This
+     * method is called by {@link PipedOutputStream#write(int)}. The least
+     * significant byte of the integer {@code oneByte} is stored at index
+     * {@code in} in the {@code buffer}.
+     * <p>
+     * This method blocks as long as {@code buffer} is full.
      * 
      * @param oneByte
-     *            the byte to store into the pipe.
-     * 
+     *            the byte to store in this pipe.
+     * @throws InterruptedIOException
+     *             if the {@code buffer} is full and the thread that has called
+     *             this method is interrupted.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or the thread that has last read
+     *             from this stream is no longer alive.
      */
     protected synchronized void receive(int oneByte) throws IOException {
         if (buffer == null || isClosed) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java Fri May  1 08:08:59 2009
@@ -20,9 +20,9 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * PipedOutputStream is a class which places information on a communications
- * pipe. When two threads want to pass data back and forth, one creates a piped
- * output stream and the other creates a piped input stream.
+ * Places information on a communications pipe. When two threads want to pass
+ * data back and forth, one creates a piped output stream and the other one
+ * creates a piped input stream.
  * 
  * @see PipedInputStream
  */
@@ -34,23 +34,23 @@
     private PipedInputStream dest;
 
     /**
-     * Constructs a new unconnected PipedOutputStream. The resulting Stream must
-     * be connected to a PipedInputStream before data may be written to it.
+     * Constructs a new unconnected {@code PipedOutputStream}. The resulting
+     * stream must be connected to a {@link PipedInputStream} before data can be
+     * written to it.
      */
     public PipedOutputStream() {
         super();
     }
 
     /**
-     * Constructs a new PipedOutputStream connected to the PipedInputStream
-     * <code>dest</code>. Any data written to this stream can be read from
-     * the <code>dest</code>.
+     * Constructs a new {@code PipedOutputStream} connected to the
+     * {@link PipedInputStream} {@code dest}. Any data written to this stream
+     * can be read from the target stream.
      * 
      * @param dest
-     *            the PipedInputStream to connect to.
-     * 
+     *            the piped input stream to connect to.
      * @throws IOException
-     *             if <code>dest</code> is already connected.
+     *             if this stream or {@code dest} are already connected.
      */
     public PipedOutputStream(PipedInputStream dest) throws IOException {
         super();
@@ -58,13 +58,11 @@
     }
 
     /**
-     * Close this PipedOutputStream. Any data buffered in the corresponding
-     * PipedInputStream can be read, then -1 will be returned to the reader. If
-     * this OutputStream is not connected, this method does nothing.
+     * Closes this stream. If this stream is connected to an input stream, the
+     * input stream is closed and the pipe is disconnected.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this
-     *             PipedOutputStream.
+     *             if an error occurs while closing this stream.
      */
     @Override
     public void close() throws IOException {
@@ -76,14 +74,13 @@
     }
 
     /**
-     * Connects this PipedOutputStream to a PipedInputStream. Any data written
-     * to this OutputStream becomes readable in the InputStream.
+     * Connects this stream to a {@link PipedInputStream}. Any data written to
+     * this output stream becomes readable in the input stream.
      * 
      * @param stream
-     *            the destination PipedInputStream.
-     * 
+     *            the destination input stream.
      * @throws IOException
-     *             If this Stream or the dest is already connected.
+     *             if either stream is already connected.
      */
     public void connect(PipedInputStream stream) throws IOException {
         if (null == stream) {
@@ -103,11 +100,11 @@
     }
 
     /**
-     * Notifies the readers on the PipedInputStream that bytes can be read. This
-     * method does nothing if this Stream is not connected.
+     * Notifies the readers of this {@link PipedInputStream} that bytes can be
+     * read. This method does nothing if this stream is not connected.
      * 
      * @throws IOException
-     *             If an IO error occurs during the flush.
+     *             if an I/O error occurs while flushing this stream.
      */
     @Override
     public void flush() throws IOException {
@@ -119,31 +116,32 @@
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from this byte array
-     * <code>buffer</code> starting at offset <code>index</code> to this
-     * PipedOutputStream. The written data can now be read from the destination
-     * PipedInputStream. Separate threads should be used for the reader of the
-     * PipedInputStream and the PipedOutputStream. There may be undesirable
-     * results if more than one Thread interacts a input or output pipe.
-     * 
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * {@code offset} to this stream. The written data can then be read from the
+     * connected input stream.
+     * <p>
+     * Separate threads should be used to write to a {@code PipedOutputStream}
+     * and to read from the connected {@link PipedInputStream}. If the same
+     * thread is used, a deadlock may occur.
+     *
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to write.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the index of the first byte in {@code buffer} to write.
      * @param count
-     *            number of bytes in buffer to write
-     * 
-     * @throws IOException
-     *             If the receiving thread was terminated without closing the
-     *             pipe. This case is not currently handled correctly.
+     *            the number of bytes from {@code buffer} to write to this
+     *            stream.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is bigger than the length of {@code buffer}.
      * @throws InterruptedIOException
-     *             If the pipe is full and the current thread is interrupted
+     *             if the pipe is full and the current thread is interrupted
      *             waiting for space to write data. This case is not currently
      *             handled correctly.
-     * @throws NullPointerException
-     *             If the receiver has not been connected yet.
-     * @throws IllegalArgumentException
-     *             If any of the arguments are out of bounds.
+     * @throws IOException
+     *             if this stream is not connected, if the target stream is
+     *             closed or if the thread reading from the target stream is no
+     *             longer alive. This case is currently not handled correctly.
      */
     @Override
     public void write(byte buffer[], int offset, int count) throws IOException {
@@ -155,25 +153,24 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to this
-     * PipedOutputStream. Only the low order byte of <code>oneByte</code> is
-     * written. The data can now be read from the destination PipedInputStream.
-     * Separate threads should be used for the reader of the PipedInputStream
-     * and the PipedOutputStream. There may be undesirable results if more than
-     * one Thread interacts a input or output pipe.
+     * Writes a single byte to this stream. Only the least significant byte of
+     * the integer {@code oneByte} is written. The written byte can then be read
+     * from the connected input stream.
+     * <p>
+     * Separate threads should be used to write to a {@code PipedOutputStream}
+     * and to read from the connected {@link PipedInputStream}. If the same
+     * thread is used, a deadlock may occur.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
-     * @throws IOException
-     *             If the receiving thread was terminated without closing the
-     *             pipe. This case is not currently handled correctly.
+     *            the byte to write.
      * @throws InterruptedIOException
-     *             If the pipe is full and the current thread is interrupted
+     *             if the pipe is full and the current thread is interrupted
      *             waiting for space to write data. This case is not currently
      *             handled correctly.
-     * @throws NullPointerException
-     *             If the receiver has not been connected yet.
+     * @throws IOException
+     *             if this stream is not connected, if the target stream is
+     *             closed or if the thread reading from the target stream is no
+     *             longer alive. This case is currently not handled correctly.
      */
     @Override
     public void write(int oneByte) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java Fri May  1 08:08:59 2009
@@ -20,9 +20,11 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * PipedReader is a class which receives information on a communications pipe.
- * When two threads want to pass data back and forth, one creates a piped writer
- * and the other creates a piped reader.
+ * Receives information on a communications pipe. When two threads want to pass
+ * data back and forth, one creates a piped writer and the other creates a piped
+ * reader.
+ *
+ * @see PipedWriter
  */
 public class PipedReader extends Reader {
 
@@ -38,13 +40,13 @@
     private char data[];
 
     /**
-     * The index in <code>buffer</code> where the next character will be
+     * The index in {@code buffer} where the next character will be
      * written.
      */
     private int in = -1;
 
     /**
-     * The index in <code>buffer</code> where the next character will be read.
+     * The index in {@code buffer} where the next character will be read.
      */
     private int out;
 
@@ -59,23 +61,25 @@
     private boolean isConnected;
 
     /**
-     * Constructs a new unconnected PipedReader. The resulting Reader must be
-     * connected to a PipedWriter before data may be read from it.
+     * Constructs a new unconnected {@code PipedReader}. The resulting reader
+     * must be connected to a {@code PipedWriter} before data may be read from
+     * it.
+     *
+     * @see PipedWriter
      */
     public PipedReader() {
         data = new char[PIPE_SIZE];
     }
 
     /**
-     * Constructs a new PipedReader connected to the PipedWriter
-     * <code>out</code>. Any data written to the writer can be read from the
-     * this reader.
+     * Constructs a new {@code PipedReader} connected to the {@link PipedWriter}
+     * {@code out}. Any data written to the writer can be read from the this
+     * reader.
      * 
      * @param out
-     *            the PipedWriter to connect to.
-     * 
+     *            the {@code PipedWriter} to connect to.
      * @throws IOException
-     *             if this or <code>out</code> are already connected.
+     *             if {@code out} is already connected.
      */
     public PipedReader(PipedWriter out) throws IOException {
         this();
@@ -83,11 +87,11 @@
     }
 
     /**
-     * Close this PipedReader. This implementation releases the buffer used for
+     * Closes this reader. This implementation releases the buffer used for
      * the pipe and notifies all threads waiting to read or write.
      * 
      * @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 {
@@ -101,14 +105,14 @@
     }
 
     /**
-     * Connects this PipedReader to a PipedWriter. Any data written to the
-     * Writer becomes available in this Reader.
+     * Connects this {@code PipedReader} to a {@link PipedWriter}. Any data
+     * written to the writer becomes readable in this reader.
      * 
      * @param src
-     *            the source PipedWriter.
-     * 
+     *            the writer to connect to.
      * @throws IOException
-     *             If either Writer or Reader is already connected.
+     *             if this reader is closed or already connected, or if {@code
+     *             src} is already connected.
      */
     public void connect(PipedWriter src) throws IOException {
         synchronized (lock) {
@@ -117,7 +121,7 @@
     }
 
     /**
-     * Establish the connection to the PipedWriter.
+     * Establishes the connection to the PipedWriter.
      * 
      * @throws IOException
      *             If this Reader is already connected.
@@ -135,17 +139,20 @@
     }
 
     /**
-     * Reads the next character from this Reader. Answer the character actually
-     * read or -1 if no character was read and end of reader was encountered.
-     * Separate threads should be used for the reader of the PipedReader and the
-     * PipedWriter. There may be undesirable results if more than one Thread
-     * interacts a reader or writer pipe.
-     * 
-     * @return int the character read -1 if end of reader.
-     * 
+     * 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 there is no data in the pipe, this method
+     * blocks until data is available, the end of the reader is detected or an
+     * exception is thrown.
+     * <p>
+     * Separate threads should be used to read from a {@code PipedReader} and to
+     * write to the connected {@link PipedWriter}. If the same thread is used,
+     * a deadlock may occur.
+     *
+     * @return the character read or -1 if the end of the reader has been
+     *         reached.
      * @throws IOException
-     *             If the reader is already closed or another IOException
-     *             occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     @Override
     public int read() throws IOException {
@@ -155,28 +162,34 @@
     }
 
     /**
-     * Reads at most <code>count</code> character from this PipedReader and
-     * stores them in char array <code>buffer</code> starting at
-     * <code>offset</code>. Answer the number of characters actually read or
-     * -1 if no characters were read and end of stream was encountered. Separate
-     * threads should be used for the reader of the PipedReader and the
-     * PipedWriter. There may be undesirable results if more than one Thread
-     * interacts a reader or writer pipe.
+     * Reads at most {@code count} characters from this reader and stores them
+     * in the character array {@code buffer} starting at {@code offset}. If
+     * there is no data in the pipe, this method blocks until at least one byte
+     * has been read, the end of the reader is detected or an exception is
+     * thrown.
+     * <p>
+     * Separate threads should be used to read from a {@code PipedReader} and to
+     * write to the connected {@link PipedWriter}. If the same thread is used, a
+     * deadlock may occur.
      * 
      * @param buffer
-     *            the character array in which to store the read characters.
+     *            the character array in which to store the characters read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read
-     *            characters.
+     *            the initial position in {@code bytes} to store the characters
+     *            read from this reader.
      * @param count
-     *            the maximum number of characters to store in
-     *            <code>buffer</code>.
-     * @return int the number of characters actually read or -1 if end of
-     *         reader.
-     * 
+     *            the maximum number of characters to store in {@code buffer}.
+     * @return the number of characters read or -1 if the end of the reader has
+     *         been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the size of {@code buffer}.
+     * @throws InterruptedIOException
+     *             if the thread reading from this reader is interrupted.
      * @throws IOException
-     *             If the reader is already closed or another IOException
-     *             occurs.
+     *             if this reader is closed or not connected to a writer, or if
+     *             the thread writing to the connected writer is no longer
+     *             alive.
      */
     @Override
     public int read(char[] buffer, int offset, int count) throws IOException {
@@ -261,15 +274,18 @@
     }
 
     /**
-     * Answer a boolean indicating whether or not this Reader is ready to be
-     * read. Answers true if the buffer contains characters to be read.
-     * 
-     * @return boolean <code>true</code> if there are characters ready,
-     *         <code>false</code> otherwise.
+     * 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. This
+     * implementation returns {@code true} if the internal buffer contains
+     * characters that can be read.
      * 
+     * @return always {@code false}.
      * @throws IOException
-     *             If the reader is already closed or another IOException
-     *             occurs.
+     *             if this reader is closed or not connected, or if some other
+     *             I/O error occurs.
+     * @see #read()
+     * @see #read(char[], int, int)
      */
     @Override
     public boolean ready() throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java Fri May  1 08:08:59 2009
@@ -20,9 +20,9 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * PipedWriter is a class which places information on a communications pipe.
- * When two threads want to pass data back and forth, one creates a piped writer
- * and the other creates a piped reader.
+ * Places information on a communications pipe. When two threads want to pass
+ * data back and forth, one creates a piped writer and the other creates a piped
+ * reader.
  * 
  * @see PipedReader
  */
@@ -35,23 +35,25 @@
     private boolean closed;
 
     /**
-     * Constructs a new unconnected PipedWriter. The resulting Stream must be
-     * connected to a PipedReader before data may be written to it.
+     * Constructs a new unconnected {@code PipedWriter}. The resulting writer
+     * must be connected to a {@code PipedReader} before data may be written to
+     * it.
+     *
+     * @see PipedReader
      */
     public PipedWriter() {
         super();
     }
 
     /**
-     * Constructs a new PipedWriter connected to the PipedReader
-     * <code>dest</code>. Any data written to this Writer can be read from
-     * the <code>dest</code>.
+     * Constructs a new {@code PipedWriter} connected to the {@link PipedReader}
+     * {@code dest}. Any data written to this writer can be read from {@code
+     * dest}.
      * 
      * @param dest
-     *            the PipedReader to connect to.
-     * 
-     * @throws java.io.IOException
-     *             if <code>dest</code> is already connected.
+     *            the {@code PipedReader} to connect to.
+     * @throws IOException
+     *             if {@code dest} is already connected.
      */
     public PipedWriter(PipedReader dest) throws IOException {
         super(dest);
@@ -59,12 +61,12 @@
     }
 
     /**
-     * Close this PipedWriter. Any data buffered in the corresponding
-     * PipedReader can be read, then -1 will be returned to the reader. If this
-     * Writer is not connected, this method does nothing.
+     * Closes this writer. If a {@link PipedReader} is connected to this writer,
+     * it is closed as well and the pipe is disconnected. Any data buffered in
+     * the reader can still be read.
      * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to close this PipedWriter.
+     * @throws IOException
+     *             if an error occurs while closing this writer.
      */
     @Override
     public void close() throws IOException {
@@ -79,14 +81,14 @@
     }
 
     /**
-     * Connects this PipedWriter to a PipedReader. Any data written to this
-     * Writer becomes readable in the Reader.
+     * Connects this {@code PipedWriter} to a {@link PipedReader}. Any data
+     * written to this writer becomes readable in the reader.
      * 
      * @param stream
-     *            the destination PipedReader.
-     * 
-     * @throws java.io.IOException
-     *             If this Writer or the dest is already connected.
+     *            the reader to connect to.
+     * @throws IOException
+     *             if this writer is closed or already connected, or if {@code
+     *             stream} is already connected.
      */
     public void connect(PipedReader stream) throws IOException {
         synchronized (lock) {
@@ -102,11 +104,11 @@
     }
 
     /**
-     * Notifies the readers on the PipedReader that characters can be read. This
+     * Notifies the readers of this {@code PipedReader} that characters can be read. This
      * method does nothing if this Writer is not connected.
      * 
-     * @throws java.io.IOException
-     *             If an IO error occurs during the flush.
+     * @throws IOException
+     *             if an I/O error occurs while flushing this writer.
      */
     @Override
     public void flush() throws IOException {
@@ -116,31 +118,35 @@
     }
 
     /**
-     * Writes <code>count</code> <code>chars</code> from the char array
-     * <code>buffer</code> starting at offset <code>index</code> to this
-     * PipedWriter. The written data can now be read from the destination
-     * PipedReader. Separate threads should be used for the reader of the
-     * PipedReader and the PipedWriter. There may be undesirable results if more
-     * than one Thread interacts a input or output pipe.
-     * 
+     * Writes {@code count} characters from the character array {@code buffer}
+     * starting at offset {@code index} to this writer. The written data can
+     * then be read from the connected {@link PipedReader} instance.
+     * <p>
+     * Separate threads should be used to write to a {@code PipedWriter} and to
+     * read from the connected {@code PipedReader}. If the same thread is used,
+     * a deadlock may occur.
+     *
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to write.
      * @param offset
-     *            offset in buffer to get chars
+     *            the index of the first character in {@code buffer} to write.
      * @param count
-     *            number of chars in buffer to write
-     * 
-     * @throws java.io.IOException
-     *             If the receiving thread was terminated without closing the
-     *             pipe. This case is not currently handled correctly.
-     * @throws java.io.InterruptedIOException
-     *             If the pipe is full and the current thread is interrupted
+     *            the number of characters from {@code buffer} to write to this
+     *            writer.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is bigger than the length of {@code buffer}.
+     * @throws InterruptedIOException
+     *             if the pipe is full and the current thread is interrupted
      *             waiting for space to write data. This case is not currently
      *             handled correctly.
-     * @throws java.lang.NullPointerException
-     *             If the receiver has not been connected yet.
-     * @throws java.lang.IllegalArgumentException
-     *             If any of the arguments are out of bounds.
+     * @throws IOException
+     *             if this writer is closed or not connected, if the target
+     *             reader is closed or if the thread reading from the target
+     *             reader is no longer alive. This case is currently not handled
+     *             correctly.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
      */
     @Override
     public void write(char buffer[], int offset, int count) throws IOException {
@@ -165,24 +171,24 @@
     }
 
     /**
-     * Writes the character <code>c</code> to this PipedWriter. The written
-     * data can now be read from the destination PipedReader. Separate threads
-     * should be used for the reader of the PipedReader and the PipedWriter.
-     * There may be undesirable results if more than one Thread interacts a
-     * input or output pipe.
+     * Writes a single character {@code c} to this writer. This character can
+     * then be read from the connected {@link PipedReader} instance.
+     * <p>
+     * Separate threads should be used to write to a {@code PipedWriter} and to
+     * read from the connected {@code PipedReader}. If the same thread is used,
+     * a deadlock may occur.
      * 
      * @param c
-     *            the character to be written
-     * 
-     * @throws java.io.IOException
-     *             If the receiving thread was terminated without closing the
-     *             pipe. This case is not currently handled correctly.
-     * @throws java.io.InterruptedIOException
-     *             If the pipe is full and the current thread is interrupted
+     *            the character to write.
+     * @throws InterruptedIOException
+     *             if the pipe is full and the current thread is interrupted
      *             waiting for space to write data. This case is not currently
      *             handled correctly.
-     * @throws java.lang.NullPointerException
-     *             If the receiver has not been connected yet.
+     * @throws IOException
+     *             if this writer is closed or not connected, if the target
+     *             reader is closed or if the thread reading from the target
+     *             reader is no longer alive. This case is currently not handled
+     *             correctly.
      */
     @Override
     public void write(int c) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java Fri May  1 08:08:59 2009
@@ -28,13 +28,12 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * PrintStream is a class which takes an OutputStream and provides convenience
- * methods for printing common data types in a human readable format on the
- * stream. This is not to be confused with DataOutputStream which is used for
- * encoding common data types so that they can be read back in. No IOExceptions
- * are thrown by this class. Instead, callers should call checkError() to see if
- * a problem has been encountered in this Stream.
- * 
+ * Wraps an existing {@link OutputStream} and provides convenience methods for
+ * writing common data types in a human readable format. This is not to be
+ * confused with DataOutputStream which is used for encoding common data types
+ * so that they can be read back in. No {@code IOException} is thrown by this
+ * class. Instead, callers should use {@link #checkError()} to see if a problem
+ * has occurred in this stream.
  */
 public class PrintStream extends FilterOutputStream implements Appendable,
         Closeable {
@@ -60,13 +59,14 @@
     // private Formatter formatter;
 
     /**
-     * Constructs a new PrintStream on the OutputStream <code>out</code>. All
-     * writes to the target can now take place through this PrintStream. By
-     * default, the PrintStream is set to not autoflush when a newline is
-     * encountered.
+     * Constructs a new {@code PrintStream} with {@code out} as its target
+     * stream. By default, the new print stream does not automatically flush its
+     * contents to the target stream when a newline is encountered.
      * 
      * @param out
-     *            the OutputStream to provide convenience methods on.
+     *            the target output stream.
+     * @throws NullPointerException
+     *             if {@code out} is {@code null}.
      */
     public PrintStream(OutputStream out) {
         super(out);
@@ -76,16 +76,18 @@
     }
 
     /**
-     * Constructs a new PrintStream on the OutputStream <code>out</code>. All
-     * writes to the target can now take place through this PrintStream. The
-     * PrintStream is set to not autoflush if <code>autoflush</code> is
-     * <code>true</code>.
+     * Constructs a new {@code PrintStream} with {@code out} as its target
+     * stream. The parameter {@code autoflush} determines if the print stream
+     * automatically flushes its contents to the target stream when a newline is
+     * encountered.
      * 
      * @param out
-     *            the OutputStream to provide convenience methods on.
+     *            the target output stream.
      * @param autoflush
-     *            indicates whether or not to flush contents upon encountering a
+     *            indicates whether to flush contents upon encountering a
      *            newline sequence.
+     * @throws NullPointerException
+     *             if {@code out} is {@code null}.
      */
     public PrintStream(OutputStream out, boolean autoflush) {
         super(out);
@@ -96,21 +98,22 @@
     }
 
     /**
-     * Constructs a new PrintStream on the OutputStream <code>out</code>. All
-     * writes to the target can now take place through this PrintStream. The
-     * PrintStream is set to not autoflush if <code>autoflush</code> is
-     * <code>true</code>.
+     * Constructs a new {@code PrintStream} with {@code out} as its target
+     * stream and using the character encoding {@code enc} while writing. The
+     * parameter {@code autoflush} determines if the print stream automatically
+     * flushes its contents to the target stream when a newline is encountered.
      * 
      * @param out
-     *            the OutputStream to provide convenience methods on.
+     *            the target output stream.
      * @param autoflush
      *            indicates whether or not to flush contents upon encountering a
      *            newline sequence.
      * @param enc
-     *            the non-null String describing the desired character encoding.
-     * 
+     *            the non-null string describing the desired character encoding.
+     * @throws NullPointerException
+     *             if {@code out} or {@code enc} are {@code null}.
      * @throws UnsupportedEncodingException
-     *             If the chosen encoding is not supported
+     *             if the encoding specified by {@code enc} is not supported.
      */
     public PrintStream(OutputStream out, boolean autoflush, String enc)
             throws UnsupportedEncodingException {
@@ -130,42 +133,40 @@
     }
 
     /**
-     * Constructs a new PrintStream on the file <code>file</code>. All writes
-     * to the target can now take place through this PrintStream. Its encoding
-     * character set is the default charset in the VM.
+     * Constructs a new {@code PrintStream} with {@code file} as its target. The
+     * virtual machine's default character set is used for character encoding.
      * 
      * @param file
-     *            the file to provide convenience methods on.
+     *            the target file. If the file already exists, its contents are
+     *            removed, otherwise a new file is created.
      * @throws FileNotFoundException
-     *             if the file does not exist or cannot be opened to write. Or
-     *             the file cannot be created or any problem when open the file
-     *             to write.
+     *             if an error occurs while opening or creating the target file.
      * @throws SecurityException
-     *             if the security manager exists and denies the write to the
-     *             file.
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      */
     public PrintStream(File file) throws FileNotFoundException {
         super(new FileOutputStream(file));
     }
 
     /**
-     * Constructs a new PrintStream on the file <code>file</code>. All writes
-     * to the target can now take place through this PrintStream. Its encoding
-     * character set name is <code>csn</code>.
+     * Constructs a new {@code PrintStream} with {@code file} as its target. The
+     * character set named {@code csn} is used for character encoding.
      * 
      * @param file
-     *            the file to provide convenience methods on.
+     *            the target file. If the file already exists, its contents are
+     *            removed, otherwise a new file is created.
      * @param csn
-     *            the character set name
+     *            the name of the character set used for character encoding.
      * @throws FileNotFoundException
-     *             if the file does not exist or cannot be opened to write. Or
-     *             the file cannot be created or any problem when open the file
-     *             to write.
+     *             if an error occurs while opening or creating the target file.
+     * @throws NullPointerException
+     *             if {@code csn} is {@code null}.
      * @throws SecurityException
-     *             if the security manager exists and denies the write to the
-     *             file.
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      * @throws UnsupportedEncodingException
-     *             if the chosen character set is not supported
+     *             if the encoding specified by {@code csn} is not supported.
      */
     public PrintStream(File file, String csn) throws FileNotFoundException,
             UnsupportedEncodingException {
@@ -180,42 +181,42 @@
     }
 
     /**
-     * Constructs a new PrintStream on the file the name of which is<code>fileName</code>.
-     * All writes to the target can now take place through this PrintStream. Its
-     * encoding character set is the default charset in the VM.
+     * Constructs a new {@code PrintStream} with the file identified by
+     * {@code fileName} as its target. The virtual machine's default character
+     * set is used for character encoding.
      * 
      * @param fileName
-     *            the file to provide convenience methods on.
+     *            the target file's name. If the file already exists, its
+     *            contents are removed, otherwise a new file is created.
      * @throws FileNotFoundException
-     *             if the file does not exist or cannot be opened to write. Or
-     *             the file cannot be created or any problem when open the file
-     *             to write.
+     *             if an error occurs while opening or creating the target file.
      * @throws SecurityException
-     *             if the security manager exists and denies the write to the
-     *             file.
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      */
     public PrintStream(String fileName) throws FileNotFoundException {
         this(new File(fileName));
     }
 
     /**
-     * Constructs a new PrintStream on the file the name of which is<code>fileName</code>.
-     * All writes to the target can now take place through this PrintStream. Its
-     * encoding character set name is <code>csn</code>.
+     * Constructs a new {@code PrintStream} with the file identified by
+     * {@code fileName} as its target. The character set named {@code csn} is
+     * used for character encoding.
      * 
      * @param fileName
-     *            the file to provide convenience methods on.
+     *            the target file's name. If the file already exists, its
+     *            contents are removed, otherwise a new file is created.
      * @param csn
-     *            the character set name
+     *            the name of the character set used for character encoding.
      * @throws FileNotFoundException
-     *             if the file does not exist or cannot be opened to write. Or
-     *             the file cannot be created or any problem when open the file
-     *             to write.
+     *             if an error occurs while opening or creating the target file.
+     * @throws NullPointerException
+     *             if {@code csn} is {@code null}.
      * @throws SecurityException
-     *             if the security manager exists and denies the write to the
-     *             file.
+     *             if a security manager exists and it denies writing to the
+     *             target file.
      * @throws UnsupportedEncodingException
-     *             if the chosen character set is not supported
+     *             if the encoding specified by {@code csn} is not supported.
      */
     public PrintStream(String fileName, String csn)
             throws FileNotFoundException, UnsupportedEncodingException {
@@ -223,13 +224,12 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this PrintStream 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 OutputStream is flushed.
+     * Flushes this stream and returns the value of the error flag.
      * 
-     * @return <code>true</code> if an error occurred in this PrintStream,
-     *         <code>false</code> otherwise.
+     * @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) {
@@ -239,9 +239,9 @@
     }
 
     /**
-     * Close this PrintStream. This implementation flushes and then closes the
-     * target stream. If an error occurs, set an error in this PrintStream to
-     * <code>true</code>.
+     * Closes this print stream. Flushes this stream and then closes the target
+     * stream. If an I/O error occurs, this stream's error state is set to
+     * {@code true}.
      */
     @Override
     public synchronized void close() {
@@ -257,9 +257,9 @@
     }
 
     /**
-     * Flush this PrintStream to ensure all pending data is sent out to the
-     * target OutputStream. This implementation flushes the target OutputStream.
-     * If an error occurs, set an error in this PrintStream to <code>true</code>.
+     * Ensures that all pending data is sent out to the target stream. It also
+     * flushes the target stream. If an I/O error occurs, this stream's error
+     * state is set to {@code true}.
      */
     @Override
     public synchronized void flush() {
@@ -275,50 +275,49 @@
     }
 
     /**
-     * Writes a string formatted by an intermediate <code>Formatter</code> to
-     * this stream using the given format string and arguments.
-     * <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 stream using the specified format string and arguments. 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 stream.
+     *            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 stream.
      * @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 PrintStream format(String format, Object... args) {
         return format(Locale.getDefault(), format, args);
     }
 
     /**
-     * Writes a string formatted by an intermediate <code>Formatter</code> to
-     * this stream using the given format string and arguments.
+     * Writes a string formatted by an intermediate {@link Formatter} to this
+     * stream using the specified locale, format string and arguments.
      * 
      * @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 stream.
+     *            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 stream.
      * @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 PrintStream format(Locale l, String format, Object... args) {
         if (format == null) {
@@ -330,25 +329,23 @@
 
     /**
      * Prints a formatted string. The behavior of this method is the same as
-     * this stream'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 stream'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 stream.
+     *            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 stream.
      * @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 PrintStream printf(String format, Object... args) {
         return format(format, args);
@@ -356,25 +353,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 stream'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 This stream.
+     *            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 stream.
      * @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 PrintStream printf(Locale l, String format, Object... args) {
         return format(l, format, args);
@@ -388,88 +384,100 @@
     }
 
     /**
-     * Prints the String representation of the character array parameter
-     * <code>charArray</code> to the target OutputStream.
+     * Prints the string representation of the specified character array
+     * to the target stream.
      * 
      * @param charArray
-     *            the character array to print on this PrintStream.
+     *            the character array to print to the target stream.
+     * @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 OutputStream.
+     * Prints the string representation of the specified character to the target
+     * stream.
      * 
      * @param ch
-     *            the character to print on this PrintStream.
+     *            the character to print to the target stream.
+     * @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 OutputStream.
+     * Prints the string representation of the specified double to the target
+     * stream.
      * 
      * @param dnum
-     *            the <code>double</code> to print on this PrintStream.
+     *            the double value to print to the target stream.
+     * @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 OutputStream.
+     * Prints the string representation of the specified float to the target
+     * stream.
      * 
      * @param fnum
-     *            the <code>float</code> to print on this PrintStream.
+     *            the float value to print to the target stream.
+     * @see #print(String)
      */
     public void print(float fnum) {
         print(String.valueOf(fnum));
     }
 
     /**
-     * Obtains the <code>int</code> argument as a <code>String</code> and
-     * prints it to the target {@link OutputStream}.
+     * Prints the string representation of the specified integer to the target
+     * stream.
      * 
      * @param inum
-     *            the <code>int</code> to print on this PrintStream.
+     *            the integer value to print to the target stream.
+     * @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 OutputStream.
+     * Prints the string representation of the specified long to the target
+     * stream.
      * 
      * @param lnum
-     *            the <code>long</code> to print on this PrintStream.
+     *            the long value to print to the target stream.
+     * @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 OutputStream.
+     * Prints the string representation of the specified object to the target
+     * stream.
      * 
      * @param obj
-     *            the Object to print on this PrintStream.
+     *            the object to print to the target stream.
+     * @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 OutputStream.
-     * 
+     * Prints a string to the target stream. The string is converted to an array
+     * of bytes using the encoding chosen during the construction of this
+     * stream. The bytes are then written to the target stream with
+     * {@code write(int)}.
+     * <p>
+     * If an I/O error occurs, this stream's error state is set to {@code true}.
+     *
      * @param str
-     *            the <code>String</code> to print on this PrintStream.
+     *            the string to print to the target stream.
+     * @see #write(int)
      */
     public synchronized void print(String str) {
         if (out == null) {
@@ -493,116 +501,121 @@
     }
 
     /**
-     * Prints the String representation of the <code>boolean</code> parameter
-     * <code>bool</code> to the target OutputStream.
+     * Prints the string representation of the specified boolean to the target
+     * stream.
      * 
      * @param bool
-     *            the <code>boolean</code> to print on this PrintStream.
+     *            the boolean value to print the target stream.
+     * @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 OutputStream.
-     * 
+     * Prints the string representation of the system property
+     * {@code "line.separator"} to the target stream.
      */
     public void println() {
         newline();
     }
 
     /**
-     * Prints the String representation of the character array parameter
-     * <code>charArray</code> to the target OutputStream 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
+     * stream.
      * 
      * @param charArray
-     *            the character array to print on this PrintStream.
+     *            the character array to print to the target stream.
+     * @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 OutputStream 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 stream.
      * 
      * @param ch
-     *            the character to print on this PrintStream.
+     *            the character to print to the target stream.
+     * @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 OutputStream 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 stream.
      * 
      * @param dnum
-     *            the double to print on this PrintStream.
+     *            the double value to print to the target stream.
+     * @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 OutputStream 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 stream.
      * 
      * @param fnum
-     *            the float to print on this PrintStream.
+     *            the float value to print to the target stream.
+     * @see #print(String)
      */
-    public void println(float fnum) {
+   public void println(float fnum) {
         println(String.valueOf(fnum));
     }
 
-    /**
-     * Obtains the <code>int</code> argument as a <code>String</code> and
-     * prints it to the target {@link OutputStream} 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 stream.
      * 
      * @param inum
-     *            the int to print on this PrintStream.
+     *            the integer value to print to the target stream.
+     * @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 OutputStream 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 stream.
      * 
      * @param lnum
-     *            the long to print on this PrintStream.
+     *            the long value to print to the target stream.
+     * @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 OutputStream 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 stream.
      * 
      * @param obj
-     *            the <code>Object</code> to print on this PrintStream.
+     *            the object to print to the target stream.
+     * @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 OutputStream followed by the System
-     * property <code>"line.separator"</code>.
-     * 
+     * Prints a string followed by the system property {@code "line.separator"}
+     * to the target stream. The string is converted to an array of bytes using
+     * the encoding chosen during the construction of this stream. The bytes are
+     * then written to the target stream with {@code write(int)}.
+     * <p>
+     * If an I/O error occurs, this stream's error state is set to {@code true}.
+     *
      * @param str
-     *            the <code>String</code> to print on this PrintStream.
+     *            the string to print to the target stream.
+     * @see #write(int)
      */
     public synchronized void println(String str) {
         print(str);
@@ -610,38 +623,42 @@
     }
 
     /**
-     * Prints the String representation of the <code>boolean</code> parameter
-     * <code>bool</code> to the target OutputStream 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 stream.
      * 
      * @param bool
-     *            the boolean to print on this PrintStream.
+     *            the boolean value to print to the target stream.
+     * @see #print(String)
      */
     public void println(boolean bool) {
         println(String.valueOf(bool));
     }
 
+    /**
+     * Sets the error flag of this print stream to {@code true}.
+     */
     protected void setError() {
         ioError = true;
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at <code>offset</code> to this
-     * PrintStream. This implementation writes the <code>buffer</code> to the
-     * target OutputStream and if this PrintStream is set to autoflush, flushes
-     * it. If an error occurs, set an error in this PrintStream to
-     * <code>true</code>.
-     * 
+     * Writes {@code count} bytes from {@code buffer} starting at {@code offset}
+     * to the target stream. If autoflush is set, this stream gets flushed after
+     * writing the buffer.
+     * <p>
+     * This stream's error flag is set to {@code true} if this stream is closed
+     * or an I/O error occurs.
+     *
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to be written.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the index of the first byte in {@code buffer} to write.
      * @param count
-     *            number of bytes in buffer to write
-     * 
+     *            the number of bytes in {@code buffer} to write.
      * @throws IndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is bigger than the length of {@code buffer}.
+     * @see #flush()
      */
     @Override
     public void write(byte[] buffer, int offset, int count) {
@@ -670,12 +687,13 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to this PrintStream.
-     * Only the low order byte of <code>oneByte</code> is written. This
-     * implementation writes <code>oneByte</code> to the target OutputStream.
-     * If <code>oneByte</code> is equal to the character <code>'\n'</code>
-     * and this PrintSteam is set to autoflush, the target OutputStream is
-     * flushed.
+     * Writes one byte to the target stream. Only the least significant byte of
+     * the integer {@code oneByte} is written. This stream is flushed if
+     * {@code oneByte} is equal to the character {@code '\n'} and this stream is
+     * set to autoflush.
+     * <p>
+     * This stream's error flag is set to {@code true} if it is closed or an I/O
+     * error occurs.
      * 
      * @param oneByte
      *            the byte to be written
@@ -697,13 +715,12 @@
     }
 
     /**
-     * Append a char <code>c</code> to the PrintStream. The
-     * PrintStream.append(<code>c</code>) works the same way as
-     * PrintStream.print(<code>c</code>).
+     * Appends the character {@code c} to the target stream. This method works
+     * the same way as {@link #print(char)}.
      * 
      * @param c
-     *            The character appended to the PrintStream.
-     * @return The PrintStream.
+     *            the character to append to the target stream.
+     * @return this stream.
      */
     public PrintStream append(char c) {
         print(c);
@@ -711,15 +728,14 @@
     }
 
     /**
-     * Append a CharSequence <code>csq</code> to the PrintStream. The
-     * PrintStream.append(<code>csq</code>) works the same way as
-     * PrintStream.print(<code>csq</code>.toString()). If <code>csq</code>
-     * is null, then a CharSequence just contains then "null" will be
-     * substituted for <code>csq</code>.
+     * Appends the character sequence {@code csq} to the target stream. This
+     * method works the same way as {@code PrintStream.print(csq.toString())}.
+     * If {@code csq} is {@code null}, then the string "null" is written to the
+     * target stream.
      * 
      * @param csq
-     *            The CharSequence appended to the PrintStream.
-     * @return The PrintStream.
+     *            the character sequence appended to the target stream.
+     * @return this stream.
      */
     public PrintStream append(CharSequence csq) {
         if (null == csq) {
@@ -731,26 +747,25 @@
     }
 
     /**
-     * Append a subsequence of a CharSequence <code>csq</code> to the
-     * PrintStream. The first char and the last char of the subsequnce is
-     * specified by the parameter <code>start</code> and <code>end</code>.
-     * The PrintStream.append(<code>csq</code>) works the same way as
-     * PrintStream.print (<code>csq</code>csq.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
+     * stream. This method works the same way as {@code
+     * PrintStream.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 stream.
      * 
      * @param csq
-     *            The CharSequence appended to the PrintStream.
+     *            the character sequence appended to the target stream.
      * @param start
-     *            The index of the first char in the CharSequence appended to
-     *            the PrintStream.
+     *            the index of the first char in the character sequence appended
+     *            to the target stream.
      * @param end
-     *            The index of the char after the last one in the CharSequence
-     *            appended to the PrintStream.
-     * @return The PrintStream.
+     *            the index of the character following the last character of the
+     *            subsequence appended to the target stream.
+     * @return this stream.
      * @throws IndexOutOfBoundsException
-     *             If start is less than end, end is greater than the length of
-     *             the CharSequence, or start or end is negative.
+     *             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}.
      */
     public PrintStream append(CharSequence csq, int start, int end) {
         if (null == csq) {



Mime
View raw message