harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [1/10] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/
Date Fri, 01 May 2009 08:09:01 GMT
Author: tellison
Date: Fri May  1 08:08:59 2009
New Revision: 770573

URL: http://svn.apache.org/viewvc?rev=770573&view=rev
Log:
Apply patch HARMONY-6192 (Javadocs from java.io.*)

Modified:
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/File.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileDescriptor.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileFilter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileNotFoundException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileOutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermission.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilePermissionCollection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotActiveException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/NotSerializableException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInput.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectInputValidation.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutput.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectOutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamClass.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamConstants.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ObjectStreamField.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OptionalDataException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/OutputStreamWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedOutputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PipedWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PrintWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/PushbackReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/RandomAccessFile.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Reader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SequenceInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Serializable.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SerializablePermission.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamCorruptedException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StreamTokenizer.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringBufferInputStream.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedInputStream.java Fri May  1 08:08:59 2009
@@ -20,12 +20,19 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * <code>BufferedInputStream</code> is a class which takes an input stream and
- * <em>buffers</em> the input. In this way, costly interaction with the original
- * input stream can be minimized by reading buffered amounts of data
- * infrequently. The drawback is that extra space is required to hold the buffer
- * and that copying takes place when reading that buffer.
+ * Wraps an existing {@link InputStream} and <em>buffers</em> the input.
+ * Expensive interaction with the underlying input stream is minimized, since
+ * most (smaller) requests can be satisfied by accessing the buffer alone. The
+ * drawback is that some extra space is required to hold the buffer and that
+ * copying takes place when filling that buffer, but this is usually outweighed
+ * by the performance benefits.
  * 
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
+ * <pre>
+ * BufferedInputStream buf = new BufferedInputStream(new FileInputStream(&quot;file.java&quot;));
+ * </pre>
+ *
  * @see BufferedOutputStream
  */
 public class BufferedInputStream extends FilterInputStream {
@@ -35,7 +42,7 @@
     protected volatile byte[] buf;
 
     /**
-     * The total number of bytes inside the byte array <code>buf</code>.
+     * The total number of bytes inside the byte array {@code buf}.
      */
     protected int count;
 
@@ -51,17 +58,17 @@
     protected int markpos = -1;
 
     /**
-     * The current position within the byte array <code>buf</code>.
+     * The current position within the byte array {@code buf}.
      */
     protected int pos;
 
     /**
-     * Constructs a new <code>BufferedInputStream</code> on the InputStream
-     * <code>in</code>. The default buffer size (8Kb) is allocated and all reads
+     * Constructs a new {@code BufferedInputStream} on the {@link InputStream}
+     * {@code in}. The default buffer size (8 KB) is allocated and all reads
      * can now be filtered through this stream.
      * 
      * @param in
-     *            the InputStream to buffer reads on.
+     *            the InputStream the buffer reads from.
      */
     public BufferedInputStream(InputStream in) {
         super(in);
@@ -69,14 +76,16 @@
     }
 
     /**
-     * Constructs a new BufferedInputStream on the InputStream <code>in</code>.
-     * The buffer size is specified by the parameter <code>size</code> and all
-     * reads can now be filtered through this BufferedInputStream.
+     * Constructs a new {@code BufferedInputStream} on the {@link InputStream}
+     * {@code in}. The buffer size is specified by the parameter {@code size}
+     * and all reads are now filtered through this stream.
      * 
      * @param in
-     *            the InputStream to buffer reads on.
+     *            the input stream the buffer reads from.
      * @param size
      *            the size of buffer to allocate.
+     * @throws IllegalArgumentException
+     *             if {@code size < 0}.
      */
     public BufferedInputStream(InputStream in, int size) {
         super(in);
@@ -88,14 +97,13 @@
     }
 
     /**
-     * Answers an int representing the number of bytes that are available before
-     * this BufferedInputStream will block. This method returns the number of
-     * bytes available in the buffer plus those available in the target stream.
+     * Returns the number of bytes that are available before this stream will
+     * block. This method returns the number of bytes available in the buffer
+     * plus those available in the source stream.
      * 
      * @return the number of bytes available before blocking.
-     * 
      * @throws IOException
-     *             If an error occurs in this stream.
+     *             if this stream is closed.
      */
     @Override
     public synchronized int available() throws IOException {
@@ -108,11 +116,11 @@
     }
 
     /**
-     * Close this BufferedInputStream. This implementation closes the target
-     * stream and releases any resources associated with it.
+     * Closes this stream. The source stream is closed and any resources
+     * associated with it are released.
      * 
      * @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 {
@@ -160,16 +168,17 @@
     }
 
     /**
-     * Set a Mark position in this BufferedInputStream. The parameter
-     * <code>readLimit</code> indicates how many bytes can be read before a mark
-     * is invalidated. Sending reset() will reposition the Stream back to the
-     * marked position provided <code>readLimit</code> has not been surpassed.
-     * The underlying buffer may be increased in size to allow
-     * <code>readlimit</code> number of bytes to be supported.
+     * Sets a mark position in this stream. The parameter {@code readlimit}
+     * indicates how many bytes can be read before a mark is invalidated.
+     * Calling {@code reset()} will reposition the stream back to the marked
+     * position if {@code readlimit} has not been surpassed. The underlying
+     * buffer may be increased in size to allow {@code readlimit} number of
+     * bytes to be supported.
      * 
      * @param readlimit
-     *            the number of bytes to be able to read before invalidating the
-     *            mark.
+     *            the number of bytes that can be read before the mark is
+     *            invalidated.
+     * @see #reset()
      */
     @Override
     public synchronized void mark(int readlimit) {
@@ -178,11 +187,12 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this BufferedInputStream
-     * supports mark() and reset(). This implementation answers
-     * <code>true</code>.
+     * Indicates whether {@code BufferedInputStream} supports the {@code mark()}
+     * and {@code reset()} methods.
      * 
-     * @return <code>true</code> for BufferedInputStreams.
+     * @return {@code true} for BufferedInputStreams.
+     * @see #mark(int)
+     * @see #reset()
      */
     @Override
     public boolean markSupported() {
@@ -190,16 +200,15 @@
     }
 
     /**
-     * Reads a single byte from this BufferedInputStream and returns the result
-     * as an int. The low-order byte is returned or -1 of the end of stream was
-     * encountered. If the underlying buffer does not contain any available
-     * bytes then it is filled and the first byte is returned.
-     * 
-     * @return 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 the source string has been
+     * reached. If the internal buffer does not contain any available bytes then
+     * it is filled from the source stream and the first byte is returned.
      * 
+     * @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 another IOException occurs.
      */
     @Override
     public synchronized int read() throws IOException {
@@ -233,25 +242,28 @@
     }
 
     /**
-     * Reads at most <code>length</code> bytes from this BufferedInputStream and
-     * stores them in byte array <code>buffer</code> starting at offset
-     * <code>offset</code>. Answer the number of bytes actually read or -1 if no
-     * bytes were read and end of stream was encountered. If all the buffered
-     * bytes have been used, a mark has not been set, and the requested number
-     * of bytes is larger than the receiver's buffer size, this implementation
-     * bypasses the buffer and simply places the results directly into
-     * <code>buffer</code>.
+     * Reads at most {@code length} bytes from this stream and stores them in
+     * byte array {@code buffer} starting at offset {@code offset}. Returns the
+     * number of bytes actually read or -1 if no bytes were read and the end of
+     * the stream was encountered. If all the buffered bytes have been used, a
+     * mark has not been set and the requested number of bytes is larger than
+     * the receiver's buffer size, this implementation bypasses the buffer and
+     * simply places the results directly into {@code buffer}.
      * 
      * @param buffer
-     *            the byte array in which to store the read bytes.
+     *            the byte 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 buffer} to store the bytes read
+     *            from this stream.
      * @param length
-     *            the maximum number of bytes to store in <code>buffer</code>.
+     *            the maximum number of bytes to store in {@code buffer}.
      * @return the number of bytes actually read or -1 if end of stream.
-     * 
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the size of
+     *             {@code buffer}.
      * @throws IOException
-     *             If the stream is already closed or another IOException
+     *             if the stream is already closed or another IOException
      *             occurs.
      */
     @Override
@@ -332,13 +344,13 @@
     }
 
     /**
-     * Reset this BufferedInputStream to the last marked location. If the
-     * <code>readlimit</code> has been passed or no <code>mark</code> has been
-     * set, throw IOException. This implementation resets the target stream.
+     * Resets this stream to the last marked location.
      * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed, no mark has been set or the mark is
+     *             no longer valid because more than {@code readlimit} bytes
+     *             have been read since setting the mark.
+     * @see #mark(int)
      */
     @Override
     public synchronized void reset() throws IOException {
@@ -354,17 +366,16 @@
     }
 
     /**
-     * Skips <code>amount</code> number of bytes in this BufferedInputStream.
-     * Subsequent <code>read()</code>'s will not return these bytes unless
-     * <code>reset()</code> is used.
+     * Skips {@code amount} number of bytes in this stream. Subsequent
+     * {@code read()}'s will not return these bytes unless {@code reset()} is
+     * used.
      * 
      * @param amount
-     *            the number of bytes to skip.
+     *            the number of bytes to skip. {@code skip} does nothing and
+     *            returns 0 if {@code amount} is less than zero.
      * @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 IOException occurs.
      */
     @Override
     public synchronized long skip(long amount) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedOutputStream.java Fri May  1 08:08:59 2009
@@ -20,32 +20,39 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * BufferedOutputStream is a class which takes an output stream and
- * <em>buffers</em> the writes to that stream. In this way, costly interaction
- * with the original output stream can be minimized by writing buffered amounts
- * of data infrequently. The drawback is that extra space is required to hold
- * the buffer and copying takes place when writing that buffer.
+ * Wraps an existing {@link OutputStream} and <em>buffers</em> the output.
+ * Expensive interaction with the underlying input stream is minimized, since
+ * most (smaller) requests can be satisfied by accessing the buffer alone. The
+ * drawback is that some extra space is required to hold the buffer and that
+ * copying takes place when flushing that buffer, but this is usually outweighed
+ * by the performance benefits.
  * 
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
+ * <pre>
+ * BufferedOutputStream buf = new BufferedOutputStream(new FileOutputStream(&quot;file.java&quot;));
+ * </pre>
+ *
  * @see BufferedInputStream
  */
 public class BufferedOutputStream extends FilterOutputStream {
     /**
-     * The buffer containing the bytes to be written to the target OutputStream.
+     * The buffer containing the bytes to be written to the target stream.
      */
     protected byte[] buf;
 
     /**
-     * The total number of bytes inside the byte array <code>buf</code>.
+     * The total number of bytes inside the byte array {@code buf}.
      */
     protected int count;
 
     /**
-     * Constructs a new BufferedOutputStream on the OutputStream
-     * <code>out</code>. The default buffer size (8Kb) is allocated and all
-     * writes are now filtered through this stream.
+     * Constructs a new {@code BufferedOutputStream} on the {@link OutputStream}
+     * {@code out}. The buffer size is set to the default value of 8 KB.
      * 
      * @param out
-     *            the OutputStream to buffer writes on.
+     *            the {@code OutputStream} for which write operations are
+     *            buffered.
      */
     public BufferedOutputStream(OutputStream out) {
         super(out);
@@ -53,16 +60,15 @@
     }
 
     /**
-     * Constructs a new BufferedOutputStream on the OutputStream
-     * <code>out</code>. The buffer size is set to <code>size</code> and
-     * all writes are now filtered through this stream.
+     * Constructs a new {@code BufferedOutputStream} on the {@link OutputStream}
+     * {@code out}. The buffer size is set to {@code size}.
      * 
      * @param out
-     *            the OutputStream to buffer writes on.
+     *            the output stream for which write operations are buffered.
      * @param size
      *            the size of the buffer in bytes.
      * @throws IllegalArgumentException
-     *             the size is <= 0
+     *             if {@code size <= 0}.
      */
     public BufferedOutputStream(OutputStream out, int size) {
         super(out);
@@ -74,13 +80,11 @@
     }
 
     /**
-     * Flush this BufferedOutputStream to ensure all pending data is written out
-     * to the target OutputStream. In addition, the target stream is also
-     * flushed.
+     * Flushes this stream to ensure all pending data is written out to the
+     * target stream. In addition, the target stream is flushed.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this
-     *             BufferedOutputStream.
+     *             if an error occurs attempting to flush this stream.
      */
     @Override
     public synchronized void flush() throws IOException {
@@ -89,25 +93,27 @@
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at <code>offset</code> to this
-     * BufferedOutputStream. If there is room in the buffer to hold the bytes,
-     * they are copied in. If not, the buffered bytes plus the bytes in
-     * <code>buffer</code> are written to the target stream, the target is
-     * flushed, and the buffer is cleared.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * {@code offset} to this stream. If there is room in the buffer to hold the
+     * bytes, they are copied in. If not, the buffered bytes plus the bytes in
+     * {@code buffer} are written to the target stream, the target is flushed,
+     * and the buffer is cleared.
      * 
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to be written.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the start position in {@code buffer} from where to get bytes.
      * @param length
-     *            number of bytes in buffer to write
-     * 
+     *            the number of bytes from {@code buffer} to write to this
+     *            stream.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the size of
+     *             {@code buffer}.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             BufferedOutputStream.
+     *             if an error occurs attempting to write to this stream.
      * @throws NullPointerException
-     *             If buffer is null.
+     *             if {@code buffer} is {@code null}.
      * @throws ArrayIndexOutOfBoundsException
      *             If offset or count is outside of bounds.
      */
@@ -141,19 +147,16 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to this
-     * BufferedOutputStream. Only the low order byte of <code>oneByte</code>
-     * is written. If there is room in the buffer, the byte is copied in and the
-     * count incremented. Otherwise, the buffer plus <code>oneByte</code> are
-     * written to the target stream, the target is flushed, and the buffer is
-     * reset.
+     * Writes one byte to this stream. Only the low order byte of the integer
+     * {@code oneByte} is written. If there is room in the buffer, the byte is
+     * copied into the buffer and the count incremented. Otherwise, the buffer
+     * plus {@code oneByte} are written to the target stream, the target is
+     * flushed, and the buffer is reset.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
+     *            the byte to be written.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             BufferedOutputStream.
+     *             if an error occurs attempting to write to this stream.
      */
     @Override
     public synchronized void write(int oneByte) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedReader.java Fri May  1 08:08:59 2009
@@ -20,20 +20,19 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * BufferedReader is a buffered character input reader. Buffering allows reading
- * from character streams more efficiently. If the default size of the buffer is
- * not practical, another size may be specified. Reading a character from a
- * Reader class usually involves reading a character from its Stream or
- * subsequent Reader. It is advisable to wrap a BufferedReader around those
- * Readers whose read operations may have high latency. For example, the
- * following code
+ * Wraps an existing {@link Reader} and <em>buffers</em> the input. Expensive
+ * interaction with the underlying reader is minimized, since most (smaller)
+ * requests can be satisfied by accessing the buffer alone. The drawback is that
+ * some extra space is required to hold the buffer and that copying takes place
+ * when filling that buffer, but this is usually outweighed by the performance
+ * benefits.
  * 
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
  * <pre>
- * BufferedReader inReader = new BufferedReader(new FileReader(&quot;file.java&quot;));
+ * BufferedReader buf = new BufferedReader(new FileReader(&quot;file.java&quot;));
  * </pre>
  * 
- * will buffer input for the file <code>file.java</code>.
- * 
  * @see BufferedWriter
  * @since 1.1
  */
@@ -52,12 +51,11 @@
     private int pos;
 
     /**
-     * Constructs a new BufferedReader on the Reader <code>in</code>. The
-     * default buffer size (8K) is allocated and all reads can now be filtered
-     * through this BufferedReader.
+     * Constructs a new BufferedReader on the Reader {@code in}. The
+     * buffer gets the default size (8 KB).
      * 
      * @param in
-     *            the Reader to buffer reads on.
+     *            the Reader that is buffered.
      */
     public BufferedReader(Reader in) {
         super(in);
@@ -66,16 +64,15 @@
     }
 
     /**
-     * Constructs a new BufferedReader on the Reader <code>in</code>. The
-     * buffer size is specified by the parameter <code>size</code> and all
-     * reads can now be filtered through this BufferedReader.
+     * Constructs a new BufferedReader on the Reader {@code in}. The buffer
+     * size is specified by the parameter {@code size}.
      * 
      * @param in
-     *            the Reader to buffer reads on.
+     *            the Reader that is buffered.
      * @param size
-     *            the size of buffer to allocate.
+     *            the size of the buffer to allocate.
      * @throws IllegalArgumentException
-     *             if the size is <= 0
+     *             if {@code size <= 0}.
      */
     public BufferedReader(Reader in, int size) {
         super(in);
@@ -87,12 +84,12 @@
     }
 
     /**
-     * Close the Reader. This implementation closes the Reader being filtered
-     * and releases the buffer used by this reader. If this BufferedReader has
-     * already been closed, nothing is done.
+     * Closes this reader. This implementation closes the buffered source reader
+     * and releases the buffer. Nothing is done if this reader has already been
+     * closed.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this BufferedReader.
+     *             if an error occurs while closing this reader.
      */
     @Override
     public void close() throws IOException {
@@ -137,30 +134,30 @@
     }
 
     /**
-     * Answer a boolean indicating whether or not this BufferedReader is closed.
+     * Indicates whether or not this reader is closed.
      * 
-     * @return <code>true</code> if this reader is closed, <code>false</code>
-     *         otherwise
+     * @return {@code true} if this reader is closed, {@code false}
+     *         otherwise.
      */
     private boolean isClosed() {
         return buf == null;
     }
 
     /**
-     * Set a Mark position in this BufferedReader. The parameter
-     * <code>readLimit</code> indicates how many characters can be read before
-     * a mark is invalidated. Sending reset() will reposition the reader back to
-     * the marked position provided <code>readLimit</code> has not been
-     * surpassed.
+     * Sets a mark position in this reader. The parameter {@code readlimit}
+     * indicates how many characters can be read before the mark is invalidated.
+     * Calling {@code reset()} will reposition the reader back to the marked
+     * position if {@code readlimit} has not been surpassed.
      * 
      * @param readlimit
-     *            an int representing how many characters must be read before
-     *            invalidating the mark.
-     * 
-     * @throws IOException
-     *             If an error occurs attempting mark this BufferedReader.
+     *            the number of characters that can be read before the mark is
+     *            invalidated.
      * @throws IllegalArgumentException
-     *             If readlimit is < 0
+     *             if {@code readlimit < 0}.
+     * @throws IOException
+     *             if an error occurs while setting a mark in this reader.
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public void mark(int readlimit) throws IOException {
@@ -177,11 +174,12 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this Reader supports mark()
-     * and reset(). This implementation answers <code>true</code>.
+     * Indicates whether this reader supports the {@code mark()} and
+     * {@code reset()} methods. This implementation returns {@code true}.
      * 
-     * @return <code>true</code> if mark() and reset() are supported,
-     *         <code>false</code> otherwise
+     * @return {@code true} for {@code BufferedReader}.
+     * @see #mark(int)
+     * @see #reset()
      */
     @Override
     public boolean markSupported() {
@@ -189,17 +187,16 @@
     }
 
     /**
-     * Reads a single character from this reader and returns the result as an
-     * int. The 2 higher-order characters are set to 0. If the end of reader was
-     * encountered then return -1. This implementation either returns a
-     * character from the buffer or if there are no characters available, fill
-     * the buffer then return a character or -1.
-     * 
-     * @return the character read or -1 if end of reader.
-     * 
+     * Reads a single character from this reader and returns it with the two
+     * higher-order bytes set to 0. If possible, BufferedReader returns a
+     * character from the buffer. If there are no characters available in the
+     * buffer, it fills the buffer and then returns a character. It returns -1
+     * if there are no more characters in the source reader.
+     *
+     * @return the character read or -1 if the end of the source reader has been
+     *         reached.
      * @throws IOException
-     *             If the BufferedReader is already closed or some other IO
-     *             error occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     @Override
     public int read() throws IOException {
@@ -217,26 +214,30 @@
     }
 
     /**
-     * Reads at most <code>length</code> characters from this BufferedReader
-     * and stores them at <code>offset</code> in the character array
-     * <code>buffer</code>. Returns the number of characters actually read or
-     * -1 if the end of reader was encountered. If all the buffered characters
-     * have been used, a mark has not been set, and the requested number of
-     * characters is larger than this Readers buffer size, this implementation
-     * bypasses the buffer and simply places the results directly into
-     * <code>buffer</code>.
+     * Reads at most {@code length} characters from this reader and stores them
+     * at {@code offset} in the character array {@code buffer}. Returns the
+     * number of characters actually read or -1 if the end of the source reader
+     * has been reached. If all the buffered characters have been used, a mark
+     * has not been set and the requested number of characters is larger than
+     * this readers buffer size, BufferedReader bypasses the buffer and simply
+     * places the results directly into {@code buffer}.
      * 
      * @param buffer
-     *            character array to store the read characters
+     *            the character array to store the characters read.
      * @param offset
-     *            offset in buf to store the read characters
+     *            the initial position in {@code buffer} to store the bytes read
+     *            from this reader.
      * @param length
-     *            maximum number of characters to read
-     * @return number of characters read or -1 if end of reader.
-     * 
+     *            the maximum number of characters to read, must be
+     *            non-negative.
+     * @return number of characters read or -1 if the end of the source reader
+     *         has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the size of
+     *             {@code buffer}.
      * @throws IOException
-     *             If the BufferedReader is already closed or some other IO
-     *             error occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     @Override
     public int read(char[] buffer, int offset, int length) throws IOException {
@@ -297,20 +298,16 @@
     }
 
     /**
-     * Answers a <code>String</code> representing the next line of text
-     * available in this BufferedReader. A line is represented by 0 or more
-     * characters followed by <code>'\n'</code>, <code>'\r'</code>,
-     * <code>'\r\n'</code> or end of stream. The <code>String</code> does not
-     * include the newline sequence. 
-     * In EBCDIC systems, a new line can also be represented by the 
-     * <code>'&#92;u0085'</code> (NEL) character.
-     * 
-     * @return the contents of the line or null if no characters were read
-     *         before end of stream.
+     * Returns the next line of text available from this reader. A line is
+     * represented by zero or more characters followed by {@code '\n'},
+     * {@code '\r'}, {@code "\r\n"} or the end of the reader. The string does
+     * not include the newline sequence. In EBCDIC systems, a new line can also
+     * be represented by the {@code &#92;u0085} (NEL) character.
      * 
+     * @return the contents of the line or {@code null} if no characters were
+     *         read before the end of the reader has been reached.
      * @throws IOException
-     *             If the BufferedReader is already closed or some other IO
-     *             error occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     public String readLine() throws IOException {
         synchronized (lock) {
@@ -396,19 +393,15 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether or not this Reader 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.
-     * 
-     * @return <code>true</code> if the receiver will not block when
-     *         <code>read()</code> is called, <code>false</code> if unknown
-     *         or blocking will occur.
+     * Indicates whether this reader is ready to be read without blocking.
      * 
+     * @return {@code true} if this reader will not block when {@code read} is
+     *         called, {@code false} if unknown or blocking will occur.
      * @throws IOException
-     *             If the BufferedReader 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)
+     * @see #readLine()
      */
     @Override
     public boolean ready() throws IOException {
@@ -421,13 +414,14 @@
     }
 
     /**
-     * Reset this BufferedReader's position to the last <code>mark()</code>
-     * location. Invocations of <code>read()/skip()</code> will occur from
-     * this new location. If this Reader was not marked, throw IOException.
+     * Resets this reader's position to the last {@code mark()} location.
+     * Invocations of {@code read()} and {@code skip()} will occur from this new
+     * location.
      * 
      * @throws IOException
-     *             If a problem occurred, the receiver does not support
-     *             <code>mark()/reset()</code>, or no mark has been set.
+     *             if this reader is closed or no mark has been set.
+     * @see #mark(int)
+     * @see #markSupported()
      */
     @Override
     public void reset() throws IOException {
@@ -443,20 +437,21 @@
     }
 
     /**
-     * Skips <code>amount</code> number of characters in this Reader.
-     * Subsequent <code>read()</code>'s will not return these characters
-     * unless <code>reset()</code> is used. Skipping characters may invalidate
-     * a mark if marklimit is surpassed.
+     * Skips {@code amount} characters in this reader. Subsequent
+     * {@code read()}s will not return these characters unless {@code reset()}
+     * is used. Skipping characters may invalidate a mark if {@code readlimit}
+     * is surpassed.
      * 
      * @param amount
      *            the maximum number of characters to skip.
      * @return the number of characters actually skipped.
-     * 
-     * @throws IOException
-     *             If the BufferedReader is already closed or some other IO
-     *             error occurs.
      * @throws IllegalArgumentException
-     *             If amount is negative
+     *             if {@code amount < 0}.
+     * @throws IOException
+     *             if this reader is closed or some other I/O error occurs.
+     * @see #mark(int)
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public long skip(long amount) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/BufferedWriter.java Fri May  1 08:08:59 2009
@@ -23,10 +23,19 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * BufferedWriter is for writing buffered character output. Characters written
- * to this Writer are buffered internally before being committed to the target
- * Writer.
+ * Wraps an existing {@link Writer} and <em>buffers</em> the output. Expensive
+ * interaction with the underlying reader is minimized, since most (smaller)
+ * requests can be satisfied by accessing the buffer alone. The drawback is that
+ * some extra space is required to hold the buffer and that copying takes place
+ * when filling that buffer, but this is usually outweighed by the performance
+ * benefits.
  * 
+ * <p/>A typical application pattern for the class looks like this:<p/>
+ *
+ * <pre>
+ * BufferedWriter buf = new BufferedWriter(new FileWriter(&quot;file.java&quot;));
+ * </pre>
+ *
  * @see BufferedReader
  */
 public class BufferedWriter extends Writer {
@@ -41,12 +50,12 @@
             .doPrivileged(new PriviAction<String>("line.separator")); //$NON-NLS-1$
 
     /**
-     * Constructs a new BufferedReader with <code>out</code> as the Writer on
-     * which to buffer write operations. The buffer size is set to the default,
-     * which is 8K.
+     * Constructs a new {@code BufferedWriter} with {@code out} as the writer
+     * for which to buffer write operations. The buffer size is set to the
+     * default value of 8 KB.
      * 
      * @param out
-     *            The Writer to buffer character writing on
+     *            the writer for which character writing is buffered.
      */
     public BufferedWriter(Writer out) {
         super(out);
@@ -55,14 +64,16 @@
     }
 
     /**
-     * Constructs a new BufferedReader with <code>out</code> as the Writer on
-     * which buffer write operations. The buffer size is set to
-     * <code>size</code>.
+     * Constructs a new {@code BufferedWriter} with {@code out} as the writer
+     * for which to buffer write operations. The buffer size is set to {@code
+     * size}.
      * 
      * @param out
-     *            The Writer to buffer character writing on.
+     *            the writer for which character writing is buffered.
      * @param size
-     *            The size of the buffer to use.
+     *            the size of the buffer in bytes.
+     * @throws IllegalArgumentException
+     *             if {@code size <= 0}.
      */
     public BufferedWriter(Writer out, int size) {
         super(out);
@@ -74,12 +85,12 @@
     }
 
     /**
-     * Close this BufferedWriter. The contents of the buffer are flushed, the
-     * target writer is closed, and the buffer is released. Only the first
-     * invocation of close has any effect.
+     * Closes this writer. The contents of the buffer are flushed, the target
+     * writer is closed, and the buffer is released. Only the first invocation
+     * of close has any effect.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this Writer.
+     *             if an error occurs while closing this writer.
      */
     @Override
     public void close() throws IOException {
@@ -94,11 +105,11 @@
     }
 
     /**
-     * Flush this BufferedWriter. The contents of the buffer are committed to
-     * the target writer and it is then flushed.
+     * Flushes this writer. The contents of the buffer are committed to the
+     * target writer and it is then flushed.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this Writer.
+     *             if an error occurs while flushing this writer.
      */
     @Override
     public void flush() throws IOException {
@@ -122,45 +133,44 @@
     }
 
     /**
-     * Answer a boolean indicating whether or not this BufferedWriter is closed.
+     * Indicates whether this writer is closed.
      * 
-     * @return <code>true</code> if this reader is closed, <code>false</code>
-     *         otherwise
+     * @return {@code true} if this writer is closed, {@code false} otherwise.
      */
     private boolean isClosed() {
         return out == null;
     }
 
     /**
-     * Write a newline to thie Writer. A newline is determined by the System
+     * Writes a newline to this writer. A newline is determined by the System
      * property "line.separator". The target writer may or may not be flushed
      * when a newline is written.
      * 
      * @throws IOException
-     *             If an error occurs attempting to write to this Writer.
+     *             if an error occurs attempting to write to this writer.
      */
     public void newLine() throws IOException {
         write(lineSeparator, 0, lineSeparator.length());
     }
 
     /**
-     * Writes out <code>count</code> characters starting at
-     * <code>offset</code> in <code>buf</code> to this BufferedWriter. If
-     * <code>count</code> is greater than this Writers buffer then flush the
-     * contents and also write the characters directly to the target Writer.
+     * Writes {@code count} characters starting at {@code offset} in
+     * {@code cbuf} to this writer. If {@code count} is greater than this
+     * writer's buffer, then the buffer is flushed and the characters are
+     * written directly to the target writer.
      * 
      * @param cbuf
-     *            the non-null array containing characters to write.
+     *            the array containing characters to write.
      * @param offset
-     *            offset in buf to retrieve characters
+     *            the start position in {@code cbuf} for retrieving characters.
      * @param count
-     *            maximum number of characters to write
-     * 
-     * @throws IOException
-     *             If this Writer has already been closed or some other
-     *             IOException occurs.
+     *            the maximum number of characters 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 greater than the size of
+     *             {@code cbuf}.
+     * @throws IOException
+     *             if this writer is closed or another I/O error occurs.
      */
     @Override
     public void write(char[] cbuf, int offset, int count) throws IOException {
@@ -202,16 +212,14 @@
     }
 
     /**
-     * Writes the character <code>oneChar</code> BufferedWriter. If the buffer
-     * is filled by writing this character, flush this Writer. Only the lower 2
-     * bytes are written.
+     * Writes the character {@code oneChar} to this writer. If the buffer
+     * gets full by writing this character, this writer is flushed. Only the
+     * lower two bytes of the integer {@code oneChar} are written.
      * 
      * @param oneChar
-     *            The Character to write out.
-     * 
+     *            the character to write.
      * @throws IOException
-     *             If this Writer 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 {
@@ -228,23 +236,24 @@
     }
 
     /**
-     * Writes out <code>count</code> characters starting at
-     * <code>offset</code> in <code>str</code> to this BufferedWriter. If
-     * <code>count</code> is greater than this Writers buffer then flush the
-     * contents and also write the characters directly to the target Writer.
+     * Writes {@code count} characters starting at {@code offset} in {@code str}
+     * to this writer. If {@code count} is greater than this writer's buffer,
+     * then this writer is flushed and the remaining characters are written
+     * directly to the target writer. If count is negative no characters are
+     * written to the buffer. This differs from the behavior of the superclass.
      * 
      * @param str
-     *            the non-null String containing characters to write
+     *            the non-null 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
-     * 
+     *            maximum number of characters to write.
      * @throws IOException
-     *             If this Writer has already been closed or some other
-     *             IOException occurs.
-     * @throws ArrayIndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *             if this writer has already been closed or another I/O error
+     *             occurs.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code offset + count} is greater
+     *             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/ByteArrayInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayInputStream.java Fri May  1 08:08:59 2009
@@ -18,13 +18,13 @@
 package java.io;
 
 /**
- * ByteArrayInputStream is used for streaming over a byte array.
+ * A specialized {@link InputStream } for reading the contents of a byte array.
  * 
  * @see ByteArrayOutputStream
  */
 public class ByteArrayInputStream extends InputStream {
     /**
-     * The <code>byte</code> array containing the bytes to stream over.
+     * The {@code byte} array containing the bytes to stream over.
      */
     protected byte[] buf;
 
@@ -41,15 +41,16 @@
 
     /**
      * The total number of bytes initially available in the byte array
-     * <code>buf</code>.
+     * {@code buf}.
      */
     protected int count;
 
     /**
-     * Constructs a new ByteArrayInputStream on the byte array <code>buf</code>.
+     * Constructs a new {@code ByteArrayInputStream} on the byte array
+     * {@code buf}.
      * 
      * @param buf
-     *            the byte array to stream over
+     *            the byte array to stream over.
      */
     public ByteArrayInputStream(byte buf[]) {
         this.mark = 0;
@@ -58,16 +59,16 @@
     }
 
     /**
-     * Constructs a new ByteArrayInputStream on the byte array <code>buf</code>
-     * with the position set to <code>offset</code> and the number of bytes
-     * available set to <code>offset</code> + <code>length</code>.
+     * Constructs a new {@code ByteArrayInputStream} on the byte array
+     * {@code buf} with the initial position set to {@code offset} and the
+     * number of bytes available set to {@code offset} + {@code length}.
      * 
      * @param buf
-     *            the byte array to stream over
+     *            the byte array to stream over.
      * @param offset
-     *            the offset in <code>buf</code> to start streaming at
+     *            the initial position in {@code buf} to start streaming from.
      * @param length
-     *            the number of bytes available to stream over.
+     *            the number of bytes available for streaming.
      */
     public ByteArrayInputStream(byte buf[], int offset, int length) {
         this.buf = buf;
@@ -77,9 +78,9 @@
     }
 
     /**
-     * Answers a int representing then number of bytes that are available before
-     * this ByteArrayInputStream will block. This method returns the number of
-     * bytes yet to be read from the underlying byte array.
+     * Returns the number of bytes that are available before this stream will
+     * block. This method returns the number of bytes yet to be read from the
+     * source byte array.
      * 
      * @return the number of bytes available before blocking.
      */
@@ -89,11 +90,10 @@
     }
 
     /**
-     * Close the ByteArrayInputStream. This implementation frees up resources
-     * associated with this stream.
+     * Closes this stream and frees resources associated with this stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this InputStream.
+     *             if an I/O error occurs while closing this stream.
      */
     @Override
     public void close() throws IOException {
@@ -101,12 +101,14 @@
     }
 
     /**
-     * Set a Mark position in this ByteArrayInputStream. The parameter
-     * <code>readLimit</code> is ignored. Sending reset() will reposition the
+     * Sets a mark position in this ByteArrayInputStream. The parameter
+     * {@code readlimit} is ignored. Sending {@code reset()} will reposition the
      * stream back to the marked position.
      * 
      * @param readlimit
      *            ignored.
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public synchronized void mark(int readlimit) {
@@ -114,13 +116,13 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this ByteArrayInputStream
-     * supports mark() and reset(). This implementation answers
-     * <code>true</code>.
-     * 
-     * @return <code>true</code> indicates this stream supports mark/reset,
-     *         <code>false
-     *				<code> otherwise.
+     * Indicates whether this stream supports the {@code mark()} and
+     * {@code reset()} methods. Returns {@code true} since this class supports
+     * these methods.
+     * 
+     * @return always {@code true}.
+     * @see #mark(int)
+     * @see #reset()
      */
     @Override
     public boolean markSupported() {
@@ -128,12 +130,11 @@
     }
 
     /**
-     * Reads a single byte from this ByteArrayInputStream and returns the result
-     * as an int. The low-order byte is returned or -1 of the end of stream was
-     * encountered. This implementation returns the next available byte from the
-     * target byte array.
+     * Reads a single byte from the source byte array and returns it as an
+     * integer in the range from 0 to 255. Returns -1 if the end of the source
+     * array has been reached.
      * 
-     * @return the byte read or -1 if end of stream.
+     * @return the byte read or -1 if the end of this stream has been reached.
      */
     @Override
     public synchronized int read() {
@@ -141,19 +142,25 @@
     }
 
     /**
-     * Reads at most <code>len</code> bytes from this ByteArrayInputStream and
-     * stores them in byte array <code>b</code> starting at offset
-     * <code>off</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 target byte array.
+     * Reads at most {@code len} bytes from this stream and stores
+     * them in byte array {@code b} starting at {@code offset}. This
+     * implementation reads bytes from the source byte array.
      * 
      * @param b
-     *            the byte array in which to store the read bytes.
+     *            the byte array in which to store the bytes read.
      * @param offset
-     *            the offset in <code>b</code> to store the read bytes.
+     *            the initial position in {@code b} to store the bytes read from
+     *            this stream.
      * @param length
-     *            the maximum number of bytes to store in <code>b</code>.
-     * @return the number of bytes actually read or -1 if end of stream.
+     *            the maximum number of bytes to store in {@code b}.
+     * @return the number of bytes actually read or -1 if no bytes were read and
+     *         the end of the stream was encountered.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the size of
+     *             {@code b}.
+     * @throws NullPointerException
+     *             if {@code b} is null.
      */
     @Override
     public synchronized int read(byte b[], int offset, int length) {
@@ -180,10 +187,11 @@
     }
 
     /**
-     * Reset this ByteArrayInputStream to the last marked location. This
-     * implementation resets the position to either the marked position, the
-     * start position supplied in the constructor or <code>0</code> if neither
-     * is provided.
+     * Resets this stream to the last marked location. This implementation
+     * resets the position to either the marked position, the start position
+     * supplied in the constructor or 0 if neither has been provided.
+     *
+     * @see #mark(int)
      */
     @Override
     public synchronized void reset() {
@@ -191,10 +199,10 @@
     }
 
     /**
-     * Skips <code>count</code> number of bytes in this InputStream.
-     * 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 target stream.
+     * Skips {@code count} number of bytes in this InputStream. Subsequent
+     * {@code read()}s will not return these bytes unless {@code reset()} is
+     * used. This implementation skips {@code count} number of bytes in the
+     * target stream. It does nothing and returns 0 if {@code n} is negative.
      * 
      * @param n
      *            the number of bytes to skip.

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/ByteArrayOutputStream.java Fri May  1 08:08:59 2009
@@ -20,9 +20,10 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * ByteArrayOutputStream is a class whose underlying stream is represented by a
- * byte array. As bytes are written to this stream, the local byte array may be
- * expanded to hold more bytes.
+ * A specialized {@link OutputStream} for class for writing content to an
+ * (internal) byte array. As bytes are written to this stream, the byte array
+ * may be expanded to hold more bytes. When the writing is considered to be
+ * finished, a copy of the byte array can be requested from the class.
  * 
  * @see ByteArrayInputStream
  */
@@ -40,8 +41,7 @@
     /**
      * Constructs a new ByteArrayOutputStream with a default size of 32 bytes.
      * If more than 32 bytes are written to this instance, the underlying byte
-     * array will expand to accommodate.
-     * 
+     * array will expand.
      */
     public ByteArrayOutputStream() {
         super();
@@ -49,14 +49,15 @@
     }
 
     /**
-     * Constructs a new ByteArrayOutputStream with a default size of
-     * <code>size</code> bytes. If more than <code>size</code> bytes are
-     * written to this instance, the underlying byte array will expand to
-     * accommodate.
+     * Constructs a new {@code ByteArrayOutputStream} with a default size of
+     * {@code size} bytes. If more than {@code size} bytes are written to this
+     * instance, the underlying byte array will expand.
      * 
      * @param size
-     *            an non-negative integer representing the initial size for the
-     *            underlying byte array.
+     *            initial size for the underlying byte array, must be
+     *            non-negative.
+     * @throws IllegalArgumentException
+     *             if {@code size} < 0.
      */
     public ByteArrayOutputStream(int size) {
         super();
@@ -68,11 +69,10 @@
     }
 
     /**
-     * Close this ByteArrayOutputStream. This implementation releases System
-     * resources used for this stream.
+     * Closes this stream. This releases system resources used for this stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this OutputStream.
+     *             if an error occurs while attempting to close this stream.
      */
     @Override
     public void close() throws IOException {
@@ -96,30 +96,29 @@
     }
 
     /**
-     * Reset this ByteArrayOutputStream to the beginning of the underlying byte
-     * array. All subsequent writes will overwrite any bytes previously stored
-     * in this stream.
-     * 
+     * Resets this stream to the beginning of the underlying byte array. All
+     * subsequent writes will overwrite any bytes previously stored in this
+     * stream.
      */
     public synchronized void reset() {
         count = 0;
     }
 
     /**
-     * Answers the total number of bytes written to this stream thus far.
+     * Returns the total number of bytes written to this stream so far.
      * 
-     * @return the number of bytes written to this Stream.
+     * @return the number of bytes written to this stream.
      */
     public int size() {
         return count;
     }
 
     /**
-     * Answer the contents of this ByteArrayOutputStream as a byte array. Any
+     * Returns the contents of this ByteArrayOutputStream as a byte array. Any
      * changes made to the receiver after returning will not be reflected in the
      * byte array returned to the caller.
      * 
-     * @return this streams current contents as a byte array.
+     * @return this stream's current contents as a byte array.
      */
     public synchronized byte[] toByteArray() {
         byte[] newArray = new byte[count];
@@ -128,11 +127,11 @@
     }
 
     /**
-     * Answer the contents of this ByteArrayOutputStream as a String. Any
+     * Returns the contents of this ByteArrayOutputStream as a string. Any
      * changes made to the receiver after returning will not be reflected in the
-     * String returned to the caller.
+     * string returned to the caller.
      * 
-     * @return this streams current contents as a String.
+     * @return this stream's current contents as a string.
      */
 
     @Override
@@ -141,19 +140,18 @@
     }
 
     /**
-     * Answer the contents of this ByteArrayOutputStream as a String. Each byte
-     * <code>b</code> in this stream is converted to a character
-     * <code>c</code> using the following function:
-     * <code>c == (char)(((hibyte & 0xff) << 8) | (b & 0xff))</code>. This
-     * method is deprecated and either toString(), or toString(enc) should be
-     * used.
+     * Returns the contents of this ByteArrayOutputStream as a string. Each byte
+     * {@code b} in this stream is converted to a character {@code c} using the
+     * following function:
+     * {@code c == (char)(((hibyte & 0xff) << 8) | (b & 0xff))}. This method is
+     * deprecated and either {@link #toString()} or {@link #toString(String)}
+     * should be used.
      * 
      * @param hibyte
-     *            the high byte of each resulting Unicode character
-     * @return this streams current contents as a String with the high byte set
-     *         to <code>hibyte</code>
-     * 
-     * @deprecated Use toString()
+     *            the high byte of each resulting Unicode character.
+     * @return this stream's current contents as a string with the high byte set
+     *         to {@code hibyte}.
+     * @deprecated Use {@link #toString()}.
      */
     @Deprecated
     public String toString(int hibyte) {
@@ -165,37 +163,36 @@
     }
 
     /**
-     * Answer the contents of this ByteArrayOutputStream as a String converted
-     * using the encoding declared in <code>enc</code>.
+     * Returns the contents of this ByteArrayOutputStream as a string converted
+     * according to the encoding declared in {@code enc}.
      * 
      * @param enc
-     *            A String representing the encoding to use when translating
-     *            this stream to a String.
-     * @return this streams current contents as a String.
-     * 
+     *            a string representing the encoding to use when translating
+     *            this stream to a string.
+     * @return this stream's current contents as an encoded string.
      * @throws UnsupportedEncodingException
-     *             If declared encoding is not supported
+     *             if the provided encoding is not supported.
      */
     public String toString(String enc) throws UnsupportedEncodingException {
         return new String(buf, 0, count, enc);
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at offset <code>index</code> to the
-     * ByteArrayOutputStream.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * offset {@code index} to this stream.
      * 
      * @param buffer
-     *            the buffer to be written
+     *            the buffer to be written.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the initial position in {@code buffer} to retrieve bytes.
      * @param len
-     *            number of bytes in buffer to write
-     * 
+     *            the number of bytes of {@code buffer} to write.
      * @throws NullPointerException
      *             If buffer is null.
      * @throws IndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *             if {@code offset < 0} or {@code len < 0}, or if
+     *             {@code offset + len} is greater than the length of
+     *             {@code buffer}.
      */
     @Override
     public synchronized void write(byte[] buffer, int offset, int len) {
@@ -215,11 +212,11 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to the OutputStream.
-     * Only the low order byte of <code>oneByte</code> is written.
+     * Writes the specified byte {@code oneByte} to the OutputStream. Only the
+     * low order byte of {@code oneByte} is written.
      * 
      * @param oneByte
-     *            the byte to be written
+     *            the byte to be written.
      */
     @Override
     public synchronized void write(int oneByte) {
@@ -230,14 +227,13 @@
     }
 
     /**
-     * Take the contents of this stream and write it to the output stream
-     * <code>out</code>.
+     * Takes the contents of this stream and writes it to the output stream
+     * {@code out}.
      * 
      * @param out
-     *            An OutputStream on which to write the contents of this stream.
-     * 
+     *            an OutputStream on which to write the contents of this stream.
      * @throws IOException
-     *             If an error occurs when writing to output stream
+     *             if an error occurs while writing to {@code out}.
      */
     public synchronized void writeTo(OutputStream out) throws IOException {
         out.write(buf, 0, count);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayReader.java Fri May  1 08:08:59 2009
@@ -20,22 +20,23 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * CharArrayReader is used as a buffered character input stream on a character
- * array.
+ * A specialized {@link Reader} for reading the contents of a char array.
+ *
+ * @see CharArrayWriter
  */
 public class CharArrayReader extends Reader {
     /**
-     * Buffer for characters
+     * The buffer for characters.
      */
     protected char buf[];
 
     /**
-     * Current buffer position.
+     * The current buffer position.
      */
     protected int pos;
 
     /**
-     * Current mark position.
+     * The current mark position.
      */
     protected int markedPos = -1;
 
@@ -45,13 +46,12 @@
     protected int count;
 
     /**
-     * Construct a CharArrayReader on the char array <code>buffer</code>. The
-     * size of the reader is set to the <code>length()</code> of the buffer
-     * and the Object to synchronize access through is set to
-     * <code>buffer</code>.
+     * Constructs a CharArrayReader on the char array {@code buf}. The size of
+     * the reader is set to the length of the buffer and the object to to read
+     * from is set to {@code buf}.
      * 
      * @param buf
-     *            the char array to filter reads on.
+     *            the char array from which to read.
      */
     public CharArrayReader(char[] buf) {
         super(buf);
@@ -60,18 +60,20 @@
     }
 
     /**
-     * Construct a CharArrayReader on the char array <code>buffer</code>. The
-     * size of the reader is set to the parameter <code>length()</code> and
-     * the original offset is set to <code>offset</code>.
+     * Constructs a CharArrayReader on the char array {@code buf}. The size of
+     * the reader is set to {@code length} and the start position from which to
+     * read the buffer is set to {@code offset}.
      * 
      * @param buf
-     *            the char array to filter reads on.
+     *            the char array from which to read.
      * @param offset
-     *            the offset in <code>buf</code> to start streaming at.
+     *            the index of the first character in {@code buf} to read.
      * @param length
-     *            the number of characters available to stream over.
+     *            the number of characters that can be read from {@code buf}.
+     * @throws IllegalArgumentException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset} is greater than the size of {@code buf} .
      */
-
     public CharArrayReader(char[] buf, int offset, int length) {
         super(buf);
         if (offset < 0 || offset > buf.length || length < 0) {
@@ -100,37 +102,33 @@
     }
 
     /**
-     * Answer a boolean indicating whether or not this CharArrayReader is open.
+     * Indicates whether this reader is open.
      * 
-     * @return <code>true</code> if the reader is open, <code>false</code>
-     *         otherwise.
+     * @return {@code true} if the reader is open, {@code false} otherwise.
      */
     private boolean isOpen() {
         return buf != null;
     }
 
     /**
-     * Answer a boolean indicating whether or not this CharArrayReader is
-     * closed.
+     * Indicates whether this reader is closed.
      * 
-     * @return <code>true</code> if the reader is closed, <code>false</code>
-     *         otherwise.
+     * @return {@code true} if the reader is closed, {@code false} otherwise.
      */
     private boolean isClosed() {
         return buf == null;
     }
 
     /**
-     * Set a Mark position in this Reader. The parameter <code>readLimit</code>
-     * is ignored for CharArrayReaders. Sending reset() will reposition the
+     * Sets a mark position in this reader. The parameter {@code readLimit} is
+     * ignored for CharArrayReaders. Calling {@code reset()} will reposition the
      * reader back to the marked position provided the mark has not been
      * invalidated.
      * 
      * @param readLimit
      *            ignored for CharArrayReaders.
-     * 
      * @throws IOException
-     *             If an error occurs attempting to mark this CharArrayReader.
+     *             if this reader is closed.
      */
     @Override
     public void mark(int readLimit) throws IOException {
@@ -143,10 +141,12 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this CharArrayReader supports
-     * mark() and reset(). This method always returns true.
+     * Indicates whether this reader supports the {@code mark()} and
+     * {@code reset()} methods.
      * 
-     * @return indicates whether or not mark() and reset() are supported.
+     * @return {@code true} for CharArrayReader.
+     * @see #mark(int)
+     * @see #reset()
      */
     @Override
     public boolean markSupported() {
@@ -154,14 +154,14 @@
     }
 
     /**
-     * Reads a single character from this CharArrayReader and returns the result
-     * as an int. The 2 higher-order bytes are set to 0. If the end of reader
-     * was encountered then return -1.
-     * 
-     * @return int the character read or -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 no more
+     * characters are available from this reader.
+     *
+     * @return the character read as an int or -1 if the end of the reader has
+     *         been reached.
      * @throws IOException
-     *             If the CharArrayReader is already closed.
+     *             if this reader is closed.
      */
     @Override
     public int read() throws IOException {
@@ -177,22 +177,26 @@
     }
 
     /**
-     * Reads at most <code>count</code> characters from this CharArrayReader
-     * and stores them at <code>offset</code> in the character array
-     * <code>buf</code>. Returns the number of characters actually read or -1
-     * if the end of reader was encountered.
-     * 
+     * Reads at most {@code count} characters from this CharArrayReader and
+     * stores them at {@code offset} in the character array {@code buf}.
+     * Returns the number of characters actually read or -1 if the end of reader
+     * was encountered.
      * 
      * @param buffer
-     *            character array to store the read characters
+     *            the character array to store the characters read.
      * @param offset
-     *            offset in buf to store the read characters
+     *            the initial position in {@code buffer} to store the characters
+     *            read from this reader.
      * @param len
-     *            maximum number of characters to read
-     * @return number of characters read or -1 if end of reader.
-     * 
+     *            the maximum number of characters to read.
+     * @return number of characters read or -1 if the end of the reader has been
+     *         reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code len < 0}, or if
+     *             {@code offset + len} is bigger than the size of
+     *             {@code buffer}.
      * @throws IOException
-     *             If the CharArrayReader is closed.
+     *             if this reader is closed.
      */
     @Override
     public int read(char buffer[], int offset, int len) throws IOException {
@@ -216,19 +220,16 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether or not this
-     * CharArrayReader 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. The implementation in CharArrayReader
-     * always returns <code>true</code> even when it has been closed.
-     * 
-     * @return <code>true</code> if the receiver will not block when
-     *         <code>read()</code> is called, <code>false</code> if unknown
-     *         or blocking will occur.
+     * Indicates whether this reader is ready to be read without blocking.
+     * Returns {@code true} if the next {@code read} will not block. Returns
+     * {@code false} if this reader may or may not block when {@code read} is
+     * called. The implementation in CharArrayReader always returns {@code true}
+     * even when it has been closed.
      * 
+     * @return {@code true} if this reader will not block when {@code read} is
+     *         called, {@code false} if unknown or blocking will occur.
      * @throws IOException
-     *             If the CharArrayReader is closed.
+     *             if this reader is closed.
      */
     @Override
     public boolean ready() throws IOException {
@@ -241,13 +242,13 @@
     }
 
     /**
-     * Reset this CharArrayReader's position to the last <code>mark()</code>
-     * location. Invocations of <code>read()/skip()</code> will occur from
-     * this new location. If this Reader was not marked, the CharArrayReader is
-     * reset to the beginning of the String.
+     * Resets this reader's position to the last {@code mark()} location.
+     * Invocations of {@code read()} and {@code skip()} will occur from this new
+     * location. If this reader has not been marked, it is reset to the
+     * beginning of the string.
      * 
      * @throws IOException
-     *             If this CharArrayReader has already been closed.
+     *             if this reader is closed.
      */
     @Override
     public void reset() throws IOException {
@@ -260,16 +261,15 @@
     }
 
     /**
-     * Skips <code>count</code> number of characters in this CharArrayReader.
-     * Subsequent <code>read()</code>'s will not return these characters
-     * unless <code>reset()</code> is used.
+     * Skips {@code count} number of characters in this reader. Subsequent
+     * {@code read()}s will not return these characters unless {@code reset()}
+     * is used. This method does nothing and returns 0 if {@code n} is negative.
      * 
      * @param n
-     *            The number of characters to skip.
-     * @return long The number of characters actually skipped.
-     * 
+     *            the number of characters to skip.
+     * @return the number of characters actually skipped.
      * @throws IOException
-     *             If this CharArrayReader has already been closed.
+     *             if this reader is closed.
      */
     @Override
     public long skip(long n) throws IOException {



Mime
View raw message