harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [4/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/FileWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FileWriter.java Fri May  1 08:08:59 2009
@@ -18,46 +18,48 @@
 package java.io;
 
 /**
- * FileWriter is a class for writing characters out to a file. The default
- * character encoding, 8859_1 is currently used to convert characters to bytes
- * in the file.
+ * A specialized {@link Writer} that writes to a file in the file system.
+ * All write requests made by calling methods in this class are directly
+ * forwarded to the equivalent function of the underlying operating system.
+ * Since this may induce some performance penalty, in particular if many small
+ * write requests are made, a FileWriter is often wrapped by a
+ * BufferedWriter.
  * 
+ * @see BufferedWriter
  * @see FileReader
  */
 public class FileWriter extends OutputStreamWriter {
 
     /**
-     * Creates a FileWriter using the File <code>file</code>.
+     * Creates a FileWriter using the File {@code file}.
      * 
      * @param file
      *            the non-null File to write bytes to.
-     * 
      * @throws IOException
-     *             If the given file is not found
+     *             if {@code file} cannot be opened for writing.
      */
     public FileWriter(File file) throws IOException {
         super(new FileOutputStream(file));
     }
 
     /**
-     * Creates a FileWriter using the File <code>file</code>. The parameter
-     * <code>append</code> determines whether or not the file is opened and
-     * appended to or just opened empty.
+     * Creates a FileWriter using the File {@code file}. The parameter
+     * {@code append} determines whether or not the file is opened and appended
+     * to or just opened and overwritten.
      * 
      * @param file
      *            the non-null File to write bytes to.
      * @param append
-     *            should the file be appened to or opened empty.
-     * 
+     *            indicates whether or not to append to an existing file.
      * @throws IOException
-     *             If the given file is not found
+     *             if the {@code file} cannot be opened for writing.
      */
     public FileWriter(File file, boolean append) throws IOException {
         super(new FileOutputStream(file, append));
     }
 
     /**
-     * Creates a FileWriter using the existing FileDescriptor <code>fd</code>.
+     * Creates a FileWriter using the existing FileDescriptor {@code fd}.
      * 
      * @param fd
      *            the non-null FileDescriptor to write bytes to.
@@ -67,32 +69,28 @@
     }
 
     /**
-     * Creates a FileWriter using the platform dependent <code>filename</code>.
-     * See the class description for how characters are converted to bytes.
+     * Creates a FileWriter using the platform dependent {@code filename}.
      * 
      * @param filename
      *            the non-null name of the file to write bytes to.
-     * 
      * @throws IOException
-     *             If the given file is not found
+     *             if the file cannot be opened for writing.
      */
     public FileWriter(String filename) throws IOException {
         super(new FileOutputStream(new File(filename)));
     }
 
     /**
-     * Creates a FileWriter using the platform dependent <code>filename</code>.
-     * See the class description for how characters are converted to bytes. The
-     * parameter <code>append</code> determines whether or not the file is
-     * opened and appended to or just opened empty.
+     * Creates a FileWriter using the platform dependent {@code filename}. The
+     * parameter {@code append} determines whether or not the file is opened and
+     * appended to or just opened and overwritten.
      * 
      * @param filename
      *            the non-null name of the file to write bytes to.
      * @param append
-     *            should the file be appened to or opened empty.
-     * 
+     *            indicates whether or not to append to an existing file.
      * @throws IOException
-     *             If the given file is not found
+     *             if the {@code file} cannot be opened for writing.
      */
     public FileWriter(String filename, boolean append) throws IOException {
         super(new FileOutputStream(filename, append));

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilenameFilter.java Fri May  1 08:08:59 2009
@@ -18,8 +18,8 @@
 package java.io;
 
 /**
- * FilenameFilter is an interface which declares methods for filtering file
- * names in the <code>list</code> method of File.
+ * An interface for filtering {@link File} objects based on their names
+ * or the directory they reside in.
  * 
  * @see File
  * @see File#list(FilenameFilter)
@@ -27,14 +27,15 @@
 public interface FilenameFilter {
 
     /**
-     * Answers a boolean if a specific filename matches a filter.
+     * Indicates if a specific filename matches this filter.
      * 
      * @param dir
-     *            the directory in which the <code>filename</code> was found.
+     *            the directory in which the {@code filename} was found.
      * @param filename
-     *            the name of the file in <code>dir</dir> to test.
-     * @return 		boolean		<code>true</code> if the filename matches the filter and can be included
-     *							in the list, <code>false</code> otherwise.
+     *            the name of the file in {@code dir} to test.
+     * @return  {@code true} if the filename matches the filter
+     *            and can be included in the list, {@code false}
+     *            otherwise.
      */
     public abstract boolean accept(File dir, String filename);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterInputStream.java Fri May  1 08:08:59 2009
@@ -18,26 +18,28 @@
 package java.io;
 
 /**
- * FilteredInputStream is a class which takes an input stream and
- * <em>filters</em> the input in some way. The filtered view may be a buffered
- * view or one which uncompresses data before returning bytes read.
- * FilterInputStreams are meant for byte streams.
+ * Wraps an existing {@link InputStream} and performs some transformation on
+ * the input data while it is being read. Transformations can be anything from a
+ * simple byte-wise filtering input data to an on-the-fly compression or
+ * decompression of the underlying stream. Input streams that wrap another input
+ * stream and provide some additional functionality on top of it usually inherit
+ * from this class.
  * 
  * @see FilterOutputStream
  */
 public class FilterInputStream extends InputStream {
 
     /**
-     * The target InputStream which is being filtered.
+     * The source input stream that is filtered.
      */
     protected volatile InputStream in;
 
     /**
-     * Constructs a new FilterInputStream on the InputStream <code>in</code>.
-     * All reads are now filtered through this stream.
+     * Constructs a new {@code FilterInputStream} with the specified input
+     * stream as source.
      * 
      * @param in
-     *            The non-null InputStream to filter reads on.
+     *            the non-null InputStream to filter reads on.
      */
     protected FilterInputStream(InputStream in) {
         super();
@@ -45,14 +47,12 @@
     }
 
     /**
-     * Answers a int representing the number of bytes that are available before
-     * this FilterInputStream will block. This method returns the number of
-     * bytes available in the target stream.
-     * 
+     * Returns the number of bytes that are available before this stream will
+     * block.
+     *
      * @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 int available() throws IOException {
@@ -60,11 +60,10 @@
     }
 
     /**
-     * Close this FilterInputStream. This implementation closes the target
-     * stream.
+     * Closes this stream. This implementation closes the filtered stream.
      * 
      * @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 {
@@ -72,17 +71,18 @@
     }
 
     /**
-     * Set a Mark position in this FilterInputStream. 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.
+     * Sets a mark position in this stream. The parameter {@code readlimit}
+     * indicates how many bytes can be read before the mark is invalidated.
+     * Sending {@code reset()} will reposition this stream back to the marked
+     * position, provided that {@code readlimit} has not been surpassed.
      * <p>
-     * This implementation sets a mark in the target stream.
-     * 
+     * This implementation sets a mark in the filtered stream.
+     *
      * @param readlimit
-     *            the number of bytes to be able to read before invalidating the
-     *            mark.
+     *            the number of bytes that can be read from this stream before
+     *            the mark is invalidated.
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public synchronized void mark(int readlimit) {
@@ -90,12 +90,15 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this FilterInputStream
-     * supports mark() and reset(). This implementation answers whether or not
-     * the target stream supports marking.
-     * 
-     * @return <code>true</code> if mark() and reset() are supported,
-     *         <code>false</code> otherwise.
+     * Indicates whether this stream supports {@code mark()} and {@code reset()}.
+     * This implementation returns whether or not the filtered stream supports
+     * marking.
+     * 
+     * @return {@code true} if {@code mark()} and {@code reset()} are supported,
+     *         {@code false} otherwise.
+     * @see #mark(int)
+     * @see #reset()
+     * @see #skip(long)
      */
     @Override
     public boolean markSupported() {
@@ -103,15 +106,14 @@
     }
 
     /**
-     * Reads a single byte from this FilterInputStream 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 a byte from the target stream.
-     * 
-     * @return the byte read or -1 if end of stream.
+     * Reads a single byte from the filtered 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.
      * 
+     * @return the byte read or -1 if the end of the filtered stream has been
+     *         reached.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if the stream is closed or another IOException occurs.
      */
     @Override
     public int read() throws IOException {
@@ -119,18 +121,17 @@
     }
 
     /**
-     * Reads bytes from this FilterInputStream and stores them in byte array
-     * <code>buffer</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 stream.
+     * Reads bytes from this stream and stores them in the byte array
+     * {@code buffer}. Returns the number of bytes actually read or -1 if no
+     * bytes were read and the end of this stream was encountered. This
+     * implementation reads bytes from the filtered stream.
      * 
      * @param buffer
      *            the byte array in which to store the read bytes.
-     * @return the number of bytes actually read or -1 if end of stream.
-     * 
+     * @return the number of bytes actually read or -1 if the end of the
+     *         filtered stream has been reached while reading.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another IOException occurs.
      */
     @Override
     public int read(byte[] buffer) throws IOException {
@@ -138,23 +139,23 @@
     }
 
     /**
-     * Reads at most <code>count</code> bytes from this FilterInputStream and
-     * stores them in byte array <code>buffer</code> starting at
-     * <code>offset</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of stream was encountered. This implementation
-     * reads bytes from the target stream.
+     * Reads at most {@code count} bytes from this stream and stores them in the
+     * byte array {@code buffer} starting at {@code offset}. Returns the number
+     * of bytes actually read or -1 if no bytes have been read and the end of
+     * this stream has been reached. This implementation reads bytes from the
+     * filtered stream.
      * 
      * @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 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 buffer}.
+     * @return the number of bytes actually read or -1 if the end of the
+     *         filtered stream has been reached while reading.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another I/O error occurs.
      */
     @Override
     public int read(byte[] buffer, int offset, int count) throws IOException {
@@ -162,14 +163,15 @@
     }
 
     /**
-     * Reset this FilterInputStream 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. This implementation
+     * resets the target stream.
      * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is already 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)
+     * @see #markSupported()
      */
     @Override
     public synchronized void reset() throws IOException {
@@ -177,18 +179,18 @@
     }
 
     /**
-     * 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 stream. Subsequent
+     * {@code read()}'s will not return these bytes unless {@code reset()} is
+     * used. This implementation skips {@code count} number of bytes in the
+     * filtered stream.
      * 
      * @param count
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
-     * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another IOException occurs.
+     * @see #mark(int)
+     * @see #reset()
      */
     @Override
     public long skip(long count) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterOutputStream.java Fri May  1 08:08:59 2009
@@ -20,37 +20,38 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * FilteredOutputStream is a class which takes an output stream and
- * <em>filters</em> the output in some way. The filtered view may be a
- * buffered output or one which compresses data before actually writing the
- * bytes. FilterOutputStreams are meant for byte streams.
+ * Wraps an existing {@link OutputStream} and performs some transformation on
+ * the output data while it is being written. Transformations can be anything
+ * from a simple byte-wise filtering output data to an on-the-fly compression or
+ * decompression of the underlying stream. Output streams that wrap another
+ * output stream and provide some additional functionality on top of it usually
+ * inherit from this class.
  * 
- * @see FilterInputStream
+ * @see FilterOutputStream
  */
 public class FilterOutputStream extends OutputStream {
 
     /**
-     * The target OutputStream for this filter.
+     * The target output stream for this filter stream.
      */
     protected OutputStream out;
 
     /**
-     * Constructs a new FilterOutputStream on the OutputStream <code>out</code>.
-     * All writes are now filtered through this stream.
+     * Constructs a new {@code FilterOutputStream} with {@code out} as its
+     * target stream.
      * 
      * @param out
-     *            the target OutputStream to filter writes on.
+     *            the target stream that this stream writes to.
      */
     public FilterOutputStream(OutputStream out) {
         this.out = out;
     }
 
     /**
-     * Close this FilterOutputStream. This implementation closes the target
-     * stream.
+     * Closes this stream. This implementation closes the target stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this stream.
+     *             if an error occurs attempting to close this stream.
      */
     @Override
     public void close() throws IOException {
@@ -64,13 +65,11 @@
     }
 
     /**
-     * Flush this FilterOutputStream to ensure all pending data is sent out to
-     * the target OutputStream. This implementation flushes the target
-     * OutputStream.
+     * Ensures that all pending data is sent out to the target stream. This
+     * implementation flushes the target stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this
-     *             FilterOutputStream.
+     *             if an error occurs attempting to flush this stream.
      */
     @Override
     public void flush() throws IOException {
@@ -78,16 +77,14 @@
     }
 
     /**
-     * Writes the entire contents of the byte array <code>buffer</code> to
-     * this FilterOutputStream. This implementation writes the
-     * <code>buffer</code> to the target stream.
+     * Writes the entire contents of the byte array {@code buffer} to this
+     * stream. This implementation writes the {@code buffer} to the target
+     * stream.
      * 
      * @param buffer
-     *            the buffer to be written
-     * 
+     *            the buffer to be written.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             FilterOutputStream.
+     *             if an I/O error occurs while writing to this stream.
      */
     @Override
     public void write(byte buffer[]) throws IOException {
@@ -95,23 +92,21 @@
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at <code>offset</code> to this
-     * FilterOutputStream. This implementation writes the <code>buffer</code>
-     * to the target OutputStream.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * {@code offset} to the target stream.
      * 
      * @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 an error occurs attempting to write to this
-     *             FilterOutputStream.
+     *            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}.
+     * @throws IOException
+     *             if an I/O error occurs while writing to this stream.
      */
     @Override
     public void write(byte buffer[], int offset, int count) throws IOException {
@@ -128,16 +123,13 @@
     }
 
     /**
-     * Writes the specified byte <code>oneByte</code> to this
-     * FilterOutputStream. Only the low order byte of <code>oneByte</code> is
-     * written. This implementation writes the byte to the target OutputStream.
+     * Writes one byte to the target stream. Only the low order byte of the
+     * integer {@code oneByte} is written.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
+     *            the byte to be written.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             FilterOutputStream.
+     *             if an I/O error occurs while writing to this stream.
      */
     @Override
     public void write(int oneByte) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterReader.java Fri May  1 08:08:59 2009
@@ -18,9 +18,12 @@
 package java.io;
 
 /**
- * FilterReader is a class which takes a Reader and <em>filters</em> the input
- * in some way. The filtered view may be a buffered view or one which
- * uncompresses data before returning characters read.
+ * Wraps an existing {@link Reader} and performs some transformation on the
+ * input data while it is being read. Transformations can be anything from a
+ * simple byte-wise filtering input data to an on-the-fly compression or
+ * decompression of the underlying reader. Readers that wrap another reader and
+ * provide some additional functionality on top of it usually inherit from this
+ * class.
  * 
  * @see FilterWriter
  */
@@ -32,8 +35,7 @@
     protected Reader in;
 
     /**
-     * Constructs a new FilterReader on the Reader <code>in</code>. All reads
-     * are now filtered through this Reader.
+     * Constructs a new FilterReader on the Reader {@code in}.
      * 
      * @param in
      *            The non-null Reader to filter reads on.
@@ -44,10 +46,10 @@
     }
 
     /**
-     * Close this FilterReader. This implementation closes the target Reader.
+     * Closes this reader. This implementation closes the filtered reader.
      * 
      * @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 {
@@ -57,20 +59,20 @@
     }
 
     /**
-     * Set a Mark position in this FilterReader. 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 bytes can be read before the mark is invalidated.
+     * Sending {@code reset()} will reposition this reader back to the marked
+     * position, provided that {@code readlimit} has not been surpassed.
      * <p>
-     * This implementation sets a mark in the target Reader.
+     * This implementation sets a mark in the filtered reader.
      * 
      * @param readlimit
-     *            the number of characters to be able to read before
-     *            invalidating the mark.
-     * 
+     *            the number of bytes that can be read from this reader before
+     *            the mark is invalidated.
      * @throws IOException
-     *             If an error occurs attempting mark this Reader.
+     *             if an error occurs while marking this reader.
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public synchronized void mark(int readlimit) throws IOException {
@@ -80,11 +82,14 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this FilterReader supports
-     * mark() and reset(). This implementation answers whether or not the target
-     * Reader supports marking.
+     * Indicates whether this reader supports {@code mark()} and {@code reset()}.
+     * This implementation returns whether the filtered reader supports marking.
      * 
-     * @return indicates whether or not mark() and reset() are supported.
+     * @return {@code true} if {@code mark()} and {@code reset()} are supported
+     *         by the filtered reader, {@code false} otherwise.
+     * @see #mark(int)
+     * @see #reset()
+     * @see #skip(long)
      */
     @Override
     public boolean markSupported() {
@@ -94,14 +99,14 @@
     }
 
     /**
-     * Reads a single char from this FilterReader and returns the result as an
-     * int. The 2 lowest order bytes are returned or -1 of the end of reader was
-     * encountered. This implementation returns a char from the target Reader.
-     * 
-     * @return The byte read or -1 if end of reader.
+     * Reads a single character from the filtered reader and returns it as an
+     * integer with the two higher-order bytes set to 0. Returns -1 if the end
+     * of the filtered reader has been reached.
      * 
+     * @return The character read or -1 if the end of the filtered reader has
+     *         been reached.
      * @throws IOException
-     *             If an error occurs attempting to read from this Reader.
+     *             if an error occurs while reading from this reader.
      */
     @Override
     public int read() throws IOException {
@@ -111,22 +116,22 @@
     }
 
     /**
-     * Reads at most <code>count</code> chars from this FilterReader and
-     * stores them in char array <code>buffer</code> starting at offset
-     * <code>offset</code>. Answer the number of chars actually read or -1 if
-     * no chars were read and end of reader was encountered. This implementation
-     * reads chars from the target reader.
+     * Reads at most {@code count} characters from the filtered reader and stores them
+     * in the byte array {@code buffer} starting at {@code offset}. Returns the
+     * number of characters actually read or -1 if no characters were read and
+     * the end of the filtered reader was encountered.
      * 
      * @param buffer
-     *            the char array in which to store the read chars.
+     *            the char array in which to store the characters read.
      * @param offset
-     *            the offset in <code>buffer</code> to store the read chars.
+     *            the initial position in {@code buffer} to store the characters
+     *            read from this reader.
      * @param count
-     *            the maximum number of chars to store in <code>buffer</code>.
-     * @return the number of chars actually read or -1 if end of reader.
-     * 
+     *            the maximum number of characters to store in {@code buffer}.
+     * @return the number of characters actually read or -1 if the end of the
+     *         filtered reader has been reached while reading.
      * @throws IOException
-     *             If an error occurs attempting to read from this Reader.
+     *             if an error occurs while reading from this reader.
      */
     @Override
     public int read(char[] buffer, int offset, int count) throws IOException {
@@ -136,19 +141,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. If
+     * the result is {@code true}, the next {@code read()} will not block. If
+     * the result is {@code false}, this reader may or may not block when
+     * {@code read()} is sent.
      * 
+     * @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 Reader is already closed or some other IO error
-     *             occurs.
+     *             if the reader is closed or some other I/O error occurs.
      */
     @Override
     public boolean ready() throws IOException {
@@ -158,16 +159,17 @@
     }
 
     /**
-     * Reset this Readers 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 implementation of
-     * <code>reset()</code> is implementation specific. See the comment for
-     * the specific Reader subclass for implementation details. The default
-     * action is to throw <code>IOException</code>.
+     * Resets this reader's position to the last marked location. Invocations of
+     * {@code read()} and {@code skip()} will occur from this new location. If
+     * this reader was not marked, the behavior depends on the implementation of
+     * {@code reset()} in the Reader subclass that is filtered by this reader.
+     * The default behavior for Reader is to throw an {@code IOException}.
      * 
      * @throws IOException
-     *             if a problem occurred or the target Reader does not support
-     *             <code>mark()/reset()</code>.
+     *             if a problem occurred or the filtered reader does not support
+     *             {@code mark()} and {@code reset()}.
+     * @see #mark(int)
+     * @see #markSupported()
      */
     @Override
     public void reset() throws IOException {
@@ -177,18 +179,19 @@
     }
 
     /**
-     * Skips <code>count</code> number of characters in this Reader.
-     * Subsequent <code>read()</code>'s will not return these characters
-     * unless <code>reset()</code> is used. The default implementation is to
-     * skip chars in the filtered Reader.
+     * Skips {@code count} characters in this reader. Subsequent {@code read()}'s
+     * will not return these characters unless {@code reset()} is used. The
+     * default implementation is to skip characters in the filtered reader.
      * 
      * @param count
      *            the maximum number of characters to skip.
      * @return the number of characters actually skipped.
-     * 
      * @throws IOException
-     *             If the Reader is already closed or some other IO error
+     *             if the filtered reader is closed or some other I/O error
      *             occurs.
+     * @see #mark(int)
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public long skip(long count) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/FilterWriter.java Fri May  1 08:08:59 2009
@@ -18,11 +18,14 @@
 package java.io;
 
 /**
- * FilterWriter is a class which takes a Writer and <em>filters</em> the
- * output in some way. The filtered view may be a buffered output or one which
- * compresses data before actually writing the bytes.
+ * Wraps an existing {@link Writer} and performs some transformation on the
+ * output data while it is being written. Transformations can be anything from a
+ * simple byte-wise filtering output data to an on-the-fly compression or
+ * decompression of the underlying writer. Writers that wrap another writer and
+ * provide some additional functionality on top of it usually inherit from this
+ * class.
  * 
- * @see FilterWriter
+ * @see FilterReader
  */
 public abstract class FilterWriter extends Writer {
 
@@ -32,8 +35,8 @@
     protected Writer out;
 
     /**
-     * Constructs a new FilterWriter on the Writer <code>out</code>. All
-     * writes are now filtered through this Writer.
+     * Constructs a new FilterWriter on the Writer {@code out}. All writes are
+     * now filtered through this writer.
      * 
      * @param out
      *            the target Writer to filter writes on.
@@ -44,13 +47,10 @@
     }
 
     /**
-     * Close this FilterWriter. Closes the Writer <code>out</code> by default.
-     * This will close any downstream Writers as well. Any additional processing
-     * required by concrete subclasses should be provided in their own
-     * <code>close</code> implementation.
+     * Closes this writer. This implementation closes the target writer.
      * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to close this FilterWriter.
+     * @throws IOException
+     *             if an error occurs attempting to close this writer.
      */
     @Override
     public void close() throws IOException {
@@ -60,11 +60,11 @@
     }
 
     /**
-     * Flush this FilteredWriter to ensure all pending data is sent out to the
-     * target Writer. This implementation flushes the target Writer.
+     * Flushes this writer to ensure all pending data is sent out to the target
+     * writer. This implementation flushes the target writer.
      * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to flush this FilterWriter.
+     * @throws IOException
+     *             if an error occurs attempting to flush this writer.
      */
     @Override
     public void flush() throws IOException {
@@ -74,20 +74,17 @@
     }
 
     /**
-     * Writes <code>count</code> <code>chars</code> from the char array
-     * <code>buffer</code> starting at offset <code>index</code> to this
-     * FilterWriter. This implementation writes the <code>buffer</code> to the
-     * target Writer.
+     * Writes {@code count} characters from the char array {@code buffer}
+     * starting at position {@code offset} to the target writer.
      * 
      * @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 an error occurs attempting to write to this FilterWriter.
+     *            the number of characters in {@code buffer} to write.
+     * @throws IOException
+     *             if an error occurs while writing to this writer.
      */
     @Override
     public void write(char buffer[], int offset, int count) throws IOException {
@@ -97,15 +94,13 @@
     }
 
     /**
-     * Writes the specified char <code>oneChar</code> to this FilterWriter.
-     * Only the 2 low order bytes of <code>oneChar</code> is written. This
-     * implementation writes the char to the target Writer.
+     * Writes the specified character {@code oneChar} to the target writer. Only the
+     * two least significant bytes of the integer {@code oneChar} are written.
      * 
      * @param oneChar
-     *            the char to be written
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to write to this FilterWriter.
+     *            the char to write to the target writer.
+     * @throws IOException
+     *             if an error occurs while writing to this writer.
      */
     @Override
     public void write(int oneChar) throws IOException {
@@ -115,20 +110,18 @@
     }
 
     /**
-     * Writes <code>count</code> <code>chars</code> from the String
-     * <code>str</code> starting at offset <code>index</code> to this
-     * FilterWriter. This implementation writes the <code>str</code> to the
-     * target Writer.
+     * Writes {@code count} characters from the string {@code str} starting at
+     * position {@code index} to this writer. This implementation writes
+     * {@code str} to the target writer.
      * 
      * @param str
-     *            the String to be written.
+     *            the string to be written.
      * @param offset
-     *            offset in str to get chars.
+     *            the index of the first character in {@code str} to write.
      * @param count
-     *            number of chars in str to write.
-     * 
-     * @throws java.io.IOException
-     *             If an error occurs attempting to write to this FilterWriter.
+     *            the number of chars in {@code str} to write.
+     * @throws IOException
+     *             if an error occurs while writing to this writer.
      */
     @Override
     public void write(String str, int offset, int count) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Flushable.java Fri May  1 08:08:59 2009
@@ -17,19 +17,15 @@
 package java.io;
 
 /**
- * <p>
- * Indicates that an output object can be flushed.
- * </p>
- * 
- * @since 1.5
+ * Defines an interface for classes that can (or need to) be flushed, typically
+ * before some output processing is considered to be finished and the object
+ * gets closed.
  */
 public interface Flushable {
     /**
-     * <p>
      * Flushes the object by writing out any buffered data to the underlying
      * output.
-     * </p>
-     * 
+     *
      * @throws IOException
      *             if there are any issues writing the data.
      */

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/IOException.java Fri May  1 08:08:59 2009
@@ -18,26 +18,28 @@
 package java.io;
 
 /**
- * This IO exception is thrown when a program encounters some sort I/O error.
- * Details may be specified in the constructor or by one of the subclasses.
+ * Signals a general, I/O-related error. Error details may be specified when
+ * calling the constructor, as usual. Note there are also several subclasses of
+ * this class for more specific error situations, such as
+ * {@link FileNotFoundException} or {@link EOFException}.
  */
 public class IOException extends Exception {
 
     private static final long serialVersionUID = 7818375828146090155L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code IOException} with its stack trace filled in.
      */
     public IOException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code IOException} with its stack trace and detail
+     * message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public IOException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStream.java Fri May  1 08:08:59 2009
@@ -18,8 +18,18 @@
 package java.io;
 
 /**
- * InputStream is an abstract class for all byte input streams. It provides
- * basic method implementations for reading bytes from a stream.
+ * The base class for all input streams. An input stream is a means of reading
+ * data from a source in a byte-wise manner.
+ * <p>
+ * Some input streams also support marking a position in the input stream and
+ * returning to this position later. This abstract class does not provide a
+ * fully working implementation, so it needs to be subclassed, and at least the
+ * {@link #read()} method needs to be overridden. Overriding some of the
+ * non-abstract methods is also often advised, since it might result in higher
+ * efficiency.
+ * <p>
+ * Many specialized input streams for purposes like reading from a file already
+ * exist in this package.
  * 
  * @see OutputStream
  */
@@ -28,7 +38,7 @@
     private static byte[] skipBuf;
 
     /**
-     * This constructor does nothing interesting. Provided for signature
+     * This constructor does nothing. It is provided for signature
      * compatibility.
      */
     public InputStream() {
@@ -36,108 +46,105 @@
     }
 
     /**
-     * Answers a int representing then number of bytes that are available before
-     * this InputStream will block. This method always returns 0. Subclasses
-     * should override and indicate the correct number of bytes available.
+     * Returns the number of bytes that are available before this stream will
+     * block. This implementation always returns 0. Subclasses should override
+     * and indicate the correct number of bytes available.
      * 
      * @return the number of bytes available before blocking.
-     * 
      * @throws IOException
-     *             If an error occurs in this InputStream.
+     *             if an error occurs in this stream.
      */
     public int available() throws IOException {
         return 0;
     }
 
     /**
-     * Close the InputStream. Concrete implementations of this class should free
+     * Closes this stream. Concrete implementations of this class should free
      * any resources during close. This implementation does nothing.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this InputStream.
+     *             if an error occurs while closing this stream.
      */
     public void close() throws IOException {
         /* empty */
     }
 
     /**
-     * Set a Mark position in this InputStream. 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.
+     * Sets a mark position in this InputStream. The parameter {@code readlimit}
+     * indicates how many bytes can be read before the mark is invalidated.
+     * Sending {@code reset()} will reposition the stream back to the marked
+     * position provided {@code readLimit} has not been surpassed.
      * <p>
      * This default implementation does nothing and concrete subclasses must
-     * provide their own implementations.
-     * 
+     * provide their own implementation.
+     *
      * @param readlimit
-     *            the number of bytes to be able to read before invalidating the
-     *            mark.
+     *            the number of bytes that can be read from this stream before
+     *            the mark is invalidated.
+     * @see #markSupported()
+     * @see #reset()
      */
     public void mark(int readlimit) {
         /* empty */
     }
 
     /**
-     * Answers a boolean indicating whether or not this InputStream supports
-     * mark() and reset(). This class provides a default implementation which
-     * answers false.
+     * Indicates whether this stream supports the {@code mark()} and
+     * {@code reset()} methods. The default implementation returns {@code false}.
      * 
-     * @return <code>true</code> if mark() and reset() are supported,
-     *         <code>false</code> otherwise.
+     * @return always {@code false}.
+     * @see #mark(int)
+     * @see #reset()
      */
     public boolean markSupported() {
         return false;
     }
 
     /**
-     * Reads a single byte from this InputStream and returns the result as an
-     * int. The low-order byte is returned or -1 of the end of stream was
-     * encountered. This abstract implementation must be provided by concrete
-     * subclasses.
-     * 
-     * @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 stream has been
+     * reached. Blocks until one byte has been read, the end of the source
+     * stream is detected or an exception is thrown.
      * 
+     * @return the byte read or -1 if the end of stream has been reached.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if the stream is closed or another IOException occurs.
      */
     public abstract int read() throws IOException;
 
     /**
-     * Reads bytes from the Stream and stores them in byte array <code>b</code>.
-     * Answer the number of bytes actually read or -1 if no bytes were read and
-     * end of stream was encountered.
+     * Reads bytes from this stream and stores them in the byte array {@code b}.
      * 
      * @param b
-     *            the byte array in which to store the read bytes.
-     * @return the number of bytes actually read or -1 if end of stream.
-     * 
+     *            the byte array in which to store the bytes read.
+     * @return the number of bytes actually read or -1 if the end of the 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.
      */
     public int read(byte b[]) throws IOException {
         return read(b, 0, b.length);
     }
 
     /**
-     * Reads at most <code>length</code> bytes from the Stream and stores them
-     * in byte array <code>b</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.
+     * Reads at most {@code length} bytes from this stream and stores them in
+     * the byte array {@code b} starting at {@code offset}.
      * 
      * @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 buffer} 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 the end of the stream
+     *         has been reached.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code b}.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if the stream is closed or another IOException occurs.
      */
     public int read(byte b[], int offset, int length) throws IOException {
         // avoid int overflow, check null b
@@ -163,34 +170,34 @@
     }
 
     /**
-     * Reset this InputStream 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 throws IOException and
-     * concrete subclasses should provide proper implementations.
-     * 
+     * Resets this stream to the last marked location. Throws an
+     * {@code IOException} if the number of bytes read since the mark has been
+     * set is greater than the limit provided to {@code mark}, or if no mark
+     * has been set.
+     * <p>
+     * This implementation always throws an {@code IOException} and concrete
+     * subclasses should provide the proper implementation.
+     *
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another IOException occurs.
      */
     public synchronized void reset() throws IOException {
         throw new IOException();
     }
 
     /**
-     * Skips <code>n</code> number of bytes in this InputStream. Subsequent
-     * <code>read()</code>'s will not return these bytes unless
-     * <code>reset()</code> is used. This method may perform multiple reads to
-     * read <code>n</code> bytes. This default implementation reads
-     * <code>n</code> bytes into a temporary buffer. Concrete subclasses
-     * should provide their own implementation.
-     * 
+     * Skips at most {@code n} bytes in this stream. It does nothing and returns
+     * 0 if {@code n} is negative. Less than {@code n} characters are skipped if
+     * the end of this stream is reached before the operation completes.
+     * <p>
+     * This default implementation reads {@code n} bytes into a temporary
+     * buffer. Concrete subclasses should provide their own implementation.
+     *
      * @param n
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
-     * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another IOException occurs.
      */
     public long skip(long n) throws IOException {
         if (n <= 0) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InputStreamReader.java Fri May  1 08:08:59 2009
@@ -32,12 +32,12 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * InputStreamReader is class for turning a byte Stream into a character Stream.
- * Data read from the source input stream is converted into characters by either
- * a default or provided character converter. By default, the encoding is
- * assumed to ISO8859_1. The InputStreamReader contains a buffer of bytes read
- * from the source input stream and converts these into characters as needed.
- * The buffer size is 8K.
+ * A class for turning a byte stream into a character stream. Data read from the
+ * source input stream is converted into characters by either a default or a
+ * provided character converter. The default encoding is taken from the
+ * "file.encoding" system property. {@code InputStreamReader} contains a buffer
+ * of bytes read from the source stream and converts these into characters as
+ * needed. The buffer size is 8K.
  * 
  * @see OutputStreamWriter
  */
@@ -53,13 +53,13 @@
     ByteBuffer bytes = ByteBuffer.allocate(BUFFER_SIZE);
 
     /**
-     * Constructs a new InputStreamReader on the InputStream <code>in</code>.
-     * Now character reading can be filtered through this InputStreamReader.
-     * This constructor assumes the default conversion of ISO8859_1
-     * (ISO-Latin-1).
+     * Constructs a new {@code InputStreamReader} on the {@link InputStream}
+     * {@code in}. This constructor sets the character converter to the encoding
+     * specified in the "file.encoding" property and falls back to ISO 8859_1
+     * (ISO-Latin-1) if the property doesn't exist.
      * 
      * @param in
-     *            the InputStream to convert to characters.
+     *            the input stream from which to read characters.
      */
     public InputStreamReader(InputStream in) {
         super(in);
@@ -74,19 +74,19 @@
     }
 
     /**
-     * Constructs a new InputStreamReader on the InputStream <code>in</code>.
-     * Now character reading can be filtered through this InputStreamReader.
-     * This constructor takes a String parameter <code>enc</code> which is the
-     * name of an encoding. If the encoding cannot be found, an
+     * Constructs a new InputStreamReader on the InputStream {@code in}. The
+     * character converter that is used to decode bytes into characters is
+     * identified by name by {@code enc}. If the encoding cannot be found, an
      * UnsupportedEncodingException error is thrown.
      * 
      * @param in
-     *            the InputStream to convert to characters.
+     *            the InputStream from which to read characters.
      * @param enc
-     *            a String describing the character converter to use.
-     * 
+     *            identifies the character converter to use.
+     * @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 InputStreamReader(InputStream in, final String enc)
             throws UnsupportedEncodingException {
@@ -107,14 +107,13 @@
     }
 
     /**
-     * Constructs a new InputStreamReader on the InputStream <code>in</code>
-     * and CharsetDecoder <code>dec</code>. Now character reading can be
-     * filtered through this InputStreamReader.
+     * Constructs a new InputStreamReader on the InputStream {@code in} and
+     * CharsetDecoder {@code dec}.
      * 
      * @param in
-     *            the InputStream to convert to characters
+     *            the source InputStream from which to read characters.
      * @param dec
-     *            a CharsetDecoder used by the character conversion
+     *            the CharsetDecoder used by the character conversion.
      */
     public InputStreamReader(InputStream in, CharsetDecoder dec) {
         super(in);
@@ -125,14 +124,13 @@
     }
 
     /**
-     * Constructs a new InputStreamReader on the InputStream <code>in</code>
-     * and Charset <code>charset</code>. Now character reading can be
-     * filtered through this InputStreamReader.
+     * Constructs a new InputStreamReader on the InputStream {@code in} and
+     * Charset {@code charset}.
      * 
      * @param in
-     *            the InputStream to convert to characters
+     *            the source InputStream from which to read characters.
      * @param charset
-     *            the Charset that specify the character converter
+     *            the Charset that defines the character converter
      */
     public InputStreamReader(InputStream in, Charset charset) {
         super(in);
@@ -144,12 +142,11 @@
     }
 
     /**
-     * Close this InputStreamReader. This implementation closes the source
-     * InputStream and releases all local storage.
+     * Closes this reader. This implementation closes the source InputStream and
+     * releases all local storage.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this
-     *             InputStreamReader.
+     *             if an error occurs attempting to close this reader.
      */
     @Override
     public void close() throws IOException {
@@ -163,12 +160,11 @@
     }
 
     /**
-     * Answer the String which identifies the encoding used to convert bytes to
-     * characters. The value <code>null</code> is returned if this Reader has
-     * been closed.
+     * Returns the name of the encoding used to convert bytes into characters.
+     * The value {@code null} is returned if this reader has been closed.
      * 
-     * @return the String describing the converter or null if this Reader is
-     *         closed.
+     * @return the name of the character converter or {@code null} if this
+     *         reader is closed.
      */
     public String getEncoding() {
         if (!isOpen()) {
@@ -178,17 +174,16 @@
     }
 
     /**
-     * Reads a single character from this InputStreamReader 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. The byte value is either
-     * obtained from converting bytes in this readers buffer or by first filling
-     * the buffer from the source InputStream and then reading from the buffer.
-     * 
-     * @return 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 the end of the
+     * reader has been reached. The byte value is either obtained from
+     * converting bytes in this reader's buffer or by first filling the buffer
+     * from the source InputStream and then reading from the buffer.
      * 
+     * @return the character read or -1 if the end of the reader has been
+     *         reached.
      * @throws IOException
-     *             If the InputStreamReader 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 {
@@ -204,24 +199,28 @@
     }
 
     /**
-     * Reads at most <code>count</code> characters from this Reader 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. The bytes are either obtained from converting bytes in
-     * this readers buffer or by first filling the buffer from the source
+     * Reads at most {@code length} characters from this reader and stores them
+     * at position {@code offset} in the character array {@code buf}. Returns
+     * the number of characters actually read or -1 if the end of the reader has
+     * been reached. The bytes are either obtained from converting bytes in this
+     * reader's buffer or by first filling the buffer from the source
      * InputStream and then reading from the buffer.
      * 
      * @param buf
-     *            character array to store the read characters
+     *            the array to store the characters read.
      * @param offset
-     *            offset in buf to store the read characters
+     *            the initial position in {@code buf} to store the characters
+     *            read from this reader.
      * @param length
-     *            maximum number of characters to read
-     * @return the number of characters read or -1 if end of reader.
-     * 
+     *            the maximum number of characters to read.
+     * @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 length < 0}, or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code buf}.
      * @throws IOException
-     *             If the InputStreamReader 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[] buf, int offset, int length) throws IOException {
@@ -306,21 +305,17 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether or not this
-     * InputStreamReader 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. This implementation answers
-     * <code>true</code> if there are bytes available in the buffer or the
-     * source InputStream has bytes available.
-     * 
-     * @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. If
+     * the result is {@code true}, the next {@code read()} will not block. If
+     * the result is {@code false} then this reader may or may not block when
+     * {@code read()} is called. This implementation returns {@code true} if
+     * there are bytes available in the buffer or the source stream has bytes
+     * available.
      * 
+     * @return {@code true} if the receiver will not block when {@code read()}
+     *         is called, {@code false} if unknown or blocking will occur.
      * @throws IOException
-     *             If the InputStreamReader is already closed or some other IO
-     *             error occurs.
+     *             if this reader is closed or some other I/O error occurs.
      */
     @Override
     public boolean ready() throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InterruptedIOException.java Fri May  1 08:08:59 2009
@@ -18,34 +18,33 @@
 package java.io;
 
 /**
- * This IO exception is thrown when a program reading or writing to a stream is
- * interrupted. This is also thrown when a socket timeout occurs before the
- * request has completed.
+ * Signals that a blocking I/O operation has been interrupted. The number of
+ * bytes that were transferred successfully before the interruption took place
+ * is stored in a field of the exception.
  */
 public class InterruptedIOException extends IOException {
 
     private static final long serialVersionUID = 4020568460727500567L;
 
     /**
-     * The number of bytes transferred before the IO interrupt occurred. The
-     * default is 0 but the value may be filled in by the caller of the
-     * constructor.
+     * The number of bytes transferred before the I/O interrupt occurred.
      */
     public int bytesTransferred;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code InterruptedIOException} with its stack trace
+     * filled in.
      */
     public InterruptedIOException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code InterruptedIOException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public InterruptedIOException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidClassException.java Fri May  1 08:08:59 2009
@@ -18,13 +18,13 @@
 package java.io;
 
 /**
- * A problem was found with the class of one of the objects being serialized or
- * deserialized. These can be
+ * Signals a problem during the serialization or or deserialization of an
+ * object. Possible reasons include:
  * <ul>
  * <li>The SUIDs of the class loaded by the VM and the serialized class info do
- * not match</li>
+ * not match.</li>
  * <li>A serializable or externalizable object cannot be instantiated (when
- * deserializing) because the empty constructor that needs to be run is not
+ * deserializing) because the no-arg constructor that needs to be run is not
  * visible or fails.</li>
  * </ul>
  * 
@@ -36,30 +36,30 @@
     private static final long serialVersionUID = -4333316296251054416L;
 
     /**
-     * The fully qualified name of the class that caused the problem
+     * The fully qualified name of the class that caused the problem.
      */
     public String classname;
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code InvalidClassException} with its stack trace and
+     * detailed message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public InvalidClassException(String detailMessage) {
         super(detailMessage);
     }
 
     /**
-     * Constructs a new instance of this class with its walkback, message and
-     * the fully qualified name of the class which caused the exception filled
-     * in.
+     * Constructs a new {@code InvalidClassException} with its stack trace,
+     * detail message and the fully qualified name of the class which caused the
+     * exception filled in.
      * 
      * @param className
-     *            The detail message for the exception.
+     *            the name of the class that caused the exception.
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public InvalidClassException(String className, String detailMessage) {
         super(detailMessage);
@@ -67,13 +67,13 @@
     }
 
     /**
-     * Answers the extra information message which was provided when the
-     * exception was created. If no message was provided at creation time, then
-     * answer null. If a message was provided and a class name which caused the
-     * exception, the values are concatenated and returned.
+     * Returns the detail message which was provided when the exception was
+     * created. {@code null} is returned if no message was provided at creation
+     * time. If a detail message as well as a class name are provided, then the
+     * values are concatenated and returned.
      * 
-     * @return The receiver's message, possibly concatenated with the name of
-     *         the class that caused the problem.
+     * @return the detail message, possibly concatenated with the name of the
+     *         class that caused the problem.
      */
     @Override
     public String getMessage() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/InvalidObjectException.java Fri May  1 08:08:59 2009
@@ -18,9 +18,7 @@
 package java.io;
 
 /**
- * The object graph loaded (deserialized) can be validated by a collection of
- * validator objects. If these decide the validation fails, then will throw
- * InvalidObjectException.
+ * Signals that, during deserialization, the validation of an object has failed.
  * 
  * @see ObjectInputStream#registerValidation(ObjectInputValidation, int)
  * @see ObjectInputValidation#validateObject()
@@ -30,11 +28,11 @@
     private static final long serialVersionUID = 3233174318281839583L;
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs an {@code InvalidObjectException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public InvalidObjectException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/LineNumberInputStream.java Fri May  1 08:08:59 2009
@@ -18,12 +18,13 @@
 package java.io;
 
 /**
- * LineNumberInputStream is a filter class which counts the number of line
- * terminators from the data read from the target InputStream. A line delimiter
- * sequence is determined by '\r', '\n', or '\r\n'. When using <code>read</code>,
- * the sequence is always translated into '\n'.
+ * Wraps an existing {@link InputStream} and counts the line terminators
+ * encountered while reading the data. Line numbering starts at 0. Recognized
+ * line terminator sequences are {@code '\r'}, {@code '\n'} and {@code "\r\n"}.
+ * When using {@code read}, line terminator sequences are always translated into
+ * {@code '\n'}.
  * 
- * @deprecated Use LineNumberReader
+ * @deprecated Use {@link LineNumberReader}
  */
 @Deprecated
 public class LineNumberInputStream extends FilterInputStream {
@@ -37,28 +38,28 @@
     private int markedLastChar;
 
     /**
-     * Constructs a new LineNumberInputStream on the InputStream <code>in</code>.
-     * All reads are now filtered through this stream and line numbers will be
-     * counted for all data read from this Stream.
+     * Constructs a new {@code LineNumberInputStream} on the {@link InputStream}
+     * {@code in}. Line numbers are counted for all data read from this stream.
      * 
      * @param in
-     *            The non-null InputStream to count line numbers.
+     *            The non-null input stream to count line numbers.
      */
     public LineNumberInputStream(InputStream in) {
         super(in);
     }
 
     /**
-     * Answers a int representing the number of bytes that are available before
-     * this LineNumberInputStream will block. This method returns the number of
-     * bytes available in the target stream. Since the target input stream may
-     * just be a sequence of <code>\r\n</code> characters and this filter only
-     * returns <code>\n<code> then <code>available</code> can only
-     * guarantee <code>target.available()/2</code> characters.
-     *
-     * @return 		int			the number of bytes available before blocking.
+     * Returns the number of bytes that are available before this stream will
+     * block.
+     * <p>
+     * Note: The source stream may just be a sequence of {@code "\r\n"} bytes
+     * which are converted into {@code '\n'} by this stream. Therefore,
+     * {@code available} returns only {@code in.available() / 2} bytes as
+     * result.
      *
-     * @throws 		IOException	If an error occurs in this stream.
+     * @return the guaranteed number of bytes available before blocking.
+     * @throws IOException
+     *             if an error occurs in this stream.
      */
     @Override
     public int available() throws IOException {
@@ -66,28 +67,29 @@
     }
 
     /**
-     * Answers a int representing the current line number for this
-     * LineNumberInputStream.
+     * Returns the current line number for this stream. Numbering starts at 0.
      * 
-     * @return int the current line number.
+     * @return the current line number.
      */
     public int getLineNumber() {
         return lineNumber;
     }
 
     /**
-     * Set a Mark position in this LineNumberInputStream. 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 lineNumber count will also be reset to the last marked
-     * lineNumber count.
+     * Sets a mark position in this stream. The parameter {@code readlimit}
+     * indicates how many bytes can be read before the mark is invalidated.
+     * Sending {@code reset()} will reposition this stream back to the marked
+     * position, provided that {@code readlimit} has not been surpassed.
+     * The line number count will also be reset to the last marked
+     * line number count.
      * <p>
-     * This implementation sets a mark in the target stream.
-     * 
+     * This implementation sets a mark in the filtered stream.
+     *
      * @param readlimit
-     *            The number of bytes to be able to read before invalidating the
-     *            mark.
+     *            the number of bytes that can be read from this stream before
+     *            the mark is invalidated.
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public void mark(int readlimit) {
@@ -97,18 +99,19 @@
     }
 
     /**
-     * Reads a single byte from this LineNumberInputStream 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 a byte from the
-     * target stream. The line number count is incremented if a line terminator
-     * is encountered. A line delimiter sequence is determined by '\r', '\n', or
-     * '\r\n'. In this method, the sequence is always translated into '\n'.
-     * 
-     * @return int The byte read or -1 if end of stream.
-     * 
+     * Reads a single byte from the filtered 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.
+     * <p>
+     * The line number count is incremented if a line terminator is encountered.
+     * Recognized line terminator sequences are {@code '\r'}, {@code '\n'} and
+     * {@code "\r\n"}. Line terminator sequences are always translated into
+     * {@code '\n'}.
+     *
+     * @return the byte read or -1 if the end of the filtered stream has been
+     *         reached.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if the stream is closed or another IOException occurs.
      */
     @SuppressWarnings("fallthrough")
     @Override
@@ -134,31 +137,33 @@
     }
 
     /**
-     * Reads at most <code>length</code> bytes from this LineNumberInputStream
-     * and stores them in byte array <code>buffer</code> starting at
-     * <code>offset</code>. Answer the number of bytes actually read or -1 if
-     * no bytes were read and end of stream was encountered. This implementation
-     * reads bytes from the target stream. The line number count is incremented
-     * if a line terminator is encountered. A line delimiter sequence is
-     * determined by '\r', '\n', or '\r\n'. In this method, the sequence is
-     * always translated into '\n'.
-     * 
+     * Reads at most {@code length} bytes from the filtered stream and stores
+     * them in the byte array {@code buffer} starting at {@code offset}.
+     * Returns the number of bytes actually read or -1 if no bytes have been
+     * read and the end of this stream has been reached.
+     * <p>
+     * The line number count is incremented if a line terminator is encountered.
+     * Recognized line terminator sequences are {@code '\r'}, {@code '\n'} and
+     * {@code "\r\n"}. Line terminator sequences are always translated into
+     * {@code '\n'}.
+     *
      * @param buffer
-     *            the non-null 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 buffer} to store the bytes read
+     *            from this stream.
      * @param length
-     *            the maximum number of bytes to store in <code>buffer</code>.
-     * @return The number of bytes actually read or -1 if end of stream.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @return the number of bytes actually read or -1 if the end of the
+     *         filtered stream has been reached while reading.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code length < 0}, or if
+     *             {@code offset + length} is greater than the length of
+     *             {@code buffer}.
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another IOException occurs.
      * @throws NullPointerException
-     *             If <code>buffer</code> is <code>null</code>.
-     * @throws IllegalArgumentException
-     *             If <code>offset</code> or <code>count</code> are out of
-     *             bounds.
+     *             if {@code buffer} is {@code null}.
      */
     @Override
     public int read(byte[] buffer, int offset, int length) throws IOException {
@@ -190,15 +195,15 @@
     }
 
     /**
-     * Reset this LineNumberInputStream 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. It also resets the line count to what is was when this Stream was
-     * marked.
+     * Resets this stream to the last marked location. It also resets the line
+     * count to what is was when this stream was marked.
      * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is already 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)
+     * @see #markSupported()
      */
     @Override
     public void reset() throws IOException {
@@ -208,31 +213,34 @@
     }
 
     /**
-     * Sets the lineNumber of this LineNumberInputStream to the specified
-     * <code>lineNumber</code>. Note that this may have side effects on the
+     * Sets the line number of this stream to the specified
+     * {@code lineNumber}. Note that this may have side effects on the
      * line number associated with the last marked position.
      * 
      * @param lineNumber
      *            the new lineNumber value.
+     * @see #mark(int)
+     * @see #reset()
      */
     public void setLineNumber(int lineNumber) {
         this.lineNumber = lineNumber;
     }
 
     /**
-     * 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 and increments
-     * the lineNumber count as bytes are skipped.
+     * Skips {@code count} number of bytes in this stream. Subsequent
+     * {@code read()}'s will not return these bytes unless {@code reset()} is
+     * used. This implementation skips {@code count} number of bytes in the
+     * filtered stream and increments the line number count whenever line
+     * terminator sequences are skipped.
      * 
      * @param count
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
-     * 
      * @throws IOException
-     *             If the stream is already closed or another IOException
-     *             occurs.
+     *             if this stream is closed or another IOException occurs.
+     * @see #mark(int)
+     * @see #read()
+     * @see #reset()
      */
     @Override
     public long skip(long count) throws IOException {



Mime
View raw message