harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [2/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/CharArrayWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharArrayWriter.java Fri May  1 08:08:59 2009
@@ -20,14 +20,17 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * CharArrayWriter is used as a character output stream on a character array.
- * The buffer used to store the written characters will grow as needed to
- * accommodate more characters as they are written.
+ * A specialized {@link Writer} for class for writing content to an (internal)
+ * char array. As bytes are written to this writer, the char array may be
+ * expanded to hold more characters. When the writing is considered to be
+ * finished, a copy of the char array can be requested from the class.
+ *
+ * @see CharArrayReader
  */
 public class CharArrayWriter extends Writer {
 
     /**
-     * Buffer for characters
+     * The buffer for characters.
      */
     protected char[] buf;
 
@@ -38,8 +41,8 @@
 
     /**
      * Constructs a new CharArrayWriter which has a buffer allocated with the
-     * default size of 32 characters. The buffer is also the <code>lock</code>
-     * used to synchronize access to this Writer.
+     * default size of 32 characters. This buffer is also used as the
+     * {@code lock} to synchronize access to this writer.
      */
     public CharArrayWriter() {
         super();
@@ -49,11 +52,13 @@
 
     /**
      * Constructs a new CharArrayWriter which has a buffer allocated with the
-     * size of <code>initialSize</code> characters. The buffer is also the
-     * <code>lock</code> used to synchronize access to this Writer.
+     * size of {@code initialSize} characters. The buffer is also used as the
+     * {@code lock} to synchronize access to this writer.
      * 
      * @param initialSize
      *            the initial size of this CharArrayWriters buffer.
+     * @throws IllegalArgumentException
+     *             if {@code initialSize < 0}.
      */
     public CharArrayWriter(int initialSize) {
         super();
@@ -65,8 +70,7 @@
     }
 
     /**
-     * Close this Writer. This is the concrete implementation required. This
-     * particular implementation does nothing.
+     * Closes this writer. The implementation in CharArrayWriter does nothing.
      */
     @Override
     public void close() {
@@ -86,8 +90,7 @@
     }
 
     /**
-     * Flush this Writer. This is the concrete implementation required. This
-     * particular implementation does nothing.
+     * Flushes this writer. The implementation in CharArrayWriter does nothing.
      */
     @Override
     public void flush() {
@@ -95,9 +98,9 @@
     }
 
     /**
-     * Reset this Writer. The current write position is reset to the beginning
+     * Resets this writer. The current write position is reset to the beginning
      * of the buffer. All written characters are lost and the size of this
-     * writer is now 0.
+     * writer is set to 0.
      */
     public void reset() {
         synchronized (lock) {
@@ -106,10 +109,11 @@
     }
 
     /**
-     * Answer the size of this Writer in characters. This number changes if this
-     * Writer is reset or as more characters are written to it.
+     * Returns the size of this writer, that is the number of characters it
+     * stores. This number changes if this writer is reset or when more
+     * characters are written to it.
      * 
-     * @return int this CharArrayWriters current size in characters.
+     * @return this CharArrayWriter's current size in characters.
      */
     public int size() {
         synchronized (lock) {
@@ -118,11 +122,11 @@
     }
 
     /**
-     * Answer the contents of the receiver as a char array. The array returned
-     * is a copy and any modifications made to this Writer after are not
-     * reflected in the result.
+     * Returns the contents of the receiver as a char array. The array returned
+     * is a copy and any modifications made to this writer after calling this
+     * method are not reflected in the result.
      * 
-     * @return char[] this CharArrayWriters contents as a new char array.
+     * @return this CharArrayWriter's contents as a new char array.
      */
     public char[] toCharArray() {
         synchronized (lock) {
@@ -133,11 +137,11 @@
     }
 
     /**
-     * Answer the contents of this CharArrayWriter as a String. The String
-     * returned is a copy and any modifications made to this Writer after are
-     * not reflected in the result.
+     * Returns the contents of this CharArrayWriter as a string. The string
+     * returned is a copy and any modifications made to this writer after
+     * calling this method are not reflected in the result.
      * 
-     * @return String this CharArrayWriters contents as a new String.
+     * @return this CharArrayWriters contents as a new string.
      */
     @Override
     public String toString() {
@@ -147,15 +151,18 @@
     }
 
     /**
-     * Writes <code>count</code> characters starting at <code>offset</code>
-     * in <code>buf</code> to this CharArrayWriter.
+     * Writes {@code count} characters starting at {@code offset} in {@code c}
+     * to this writer.
      * 
      * @param c
      *            the non-null array containing characters to write.
      * @param offset
-     *            offset in buf to retrieve characters
+     *            the index of the first character in {@code buf} to write.
      * @param len
-     *            maximum number of characters to write
+     *            maximum number of characters to write.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code len < 0}, or if
+     *             {@code offset + len} is bigger than the size of {@code c}.
      */
     @Override
     public void write(char[] c, int offset, int len) {
@@ -172,12 +179,12 @@
     }
 
     /**
-     * Writes the specified character <code>oneChar</code> to this
-     * CharArrayWriter. This implementation writes the low order two bytes to
-     * the Stream.
+     * Writes the specified character {@code oneChar} to this writer.
+     * This implementation writes the two low order bytes of the integer
+     * {@code oneChar} to the buffer.
      * 
      * @param oneChar
-     *            The character to write
+     *            the character to write.
      */
     @Override
     public void write(int oneChar) {
@@ -188,16 +195,21 @@
     }
 
     /**
-     * Writes <code>count</code> number of characters starting at
-     * <code>offset</code> from the String <code>str</code> to this
-     * CharArrayWriter.
+     * Writes {@code count} number of characters starting at {@code offset} from
+     * the string {@code str} to this CharArrayWriter.
      * 
      * @param str
-     *            the non-null String containing the characters to write.
+     *            the non-null string containing the characters to write.
      * @param offset
-     *            the starting point to retrieve characters.
+     *            the index of the first character in {@code str} to write.
      * @param len
      *            the number of characters to retrieve and write.
+     * @throws NullPointerException
+     *             if {@code str} is null.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code len < 0}, or if
+     *             {@code offset + len} is bigger than the length of
+     *             {@code str}.
      */
     @Override
     public void write(String str, int offset, int len) {
@@ -219,13 +231,14 @@
     /**
      * Writes the contents of this CharArrayWriter to another Writer. The output
      * is all the characters that have been written to the receiver since the
-     * last reset or since the creation.
+     * last reset or since it was created.
      * 
      * @param out
      *            the non-null Writer on which to write the contents.
-     * 
+     * @throws NullPointerException
+     *             if {@code out} is null.
      * @throws IOException
-     *             If an error occurs attempting to write the contents out.
+     *             if an error occurs attempting to write out the contents.
      */
     public void writeTo(Writer out) throws IOException {
         synchronized (lock) {
@@ -234,14 +247,12 @@
     }
 
     /**
-     * Append a char <code>c</code>to the CharArrayWriter. The
-     * CharArrayWriter.append(<code>c</code>) works the same way as
-     * CharArrayWriter.write(<code>c</code>).
+     * Appends a char {@code c} to the CharArrayWriter. The method works the
+     * same way as {@code write(c)}.
      * 
      * @param c
-     *            The character appended to the CharArrayWriter.
-     * @return The CharArrayWriter.
-     * @see Writer#append(char)
+     *            the character appended to the CharArrayWriter.
+     * @return this CharArrayWriter.
      */
     @Override
     public CharArrayWriter append(char c) {
@@ -250,16 +261,13 @@
     }
 
     /**
-     * Append a CharSequence <code>csq</code> to the CharArrayWriter. The
-     * CharArrayWriter.append(<code>csq</code>) works the same way as
-     * CharArrayWriter.write(<code>csq</code>.toString()). If
-     * <code>csq</code> is null, then then "null" will be substituted for
-     * <code>csq</code>.
+     * Appends a CharSequence {@code csq} to the CharArrayWriter. The method
+     * works the same way as {@code write(csq.toString())}. If {@code csq} is
+     * null, then it will be substituted with the string "null".
      * 
      * @param csq
-     *            The CharSequence appended to the CharArrayWriter.
-     * @return The CharArrayWriter
-     * @see Writer#append(CharSequence)
+     *            the CharSequence appended to the CharArrayWriter, may be null.
+     * @return this CharArrayWriter.
      */
     @Override
     public CharArrayWriter append(CharSequence csq) {
@@ -272,27 +280,25 @@
     }
 
     /**
-     * Append a subsequence of a CharSequence <code>csq</code> to the
-     * CharArrayWriter. The first char and the last char of the subsequnce is
-     * specified by the parameter <code>start</code> and <code>end</code>.
-     * The CharArrayWriter.append(<code>csq</code>) works the same way as
-     * CharArrayWriter.write(<code>csq</code>.subSequence(<code>start</code>,<code>end</code>).toString).
-     * If <code>csq</code> is null, then "null" will be substituted for
-     * <code>csq</code>.
+     * Append a subsequence of a CharSequence {@code csq} to the
+     * CharArrayWriter. The first and last characters of the subsequence are
+     * specified by the parameters {@code start} and {@code end}. The
+     * CharArrayWriter.append({@code csq}) works the same way as
+     * {@code CharArrayWriter.write(csq.subSequence(start, end).toString)}. If
+     * {@code csq} is null, then it will be substituted with the string "null".
      * 
      * @param csq
-     *            The CharSequence appended to the CharArrayWriter.
+     *            the CharSequence appended to the CharArrayWriter, may be null.
      * @param start
-     *            The index of the first char in the CharSequence appended to
-     *            the CharArrayWriter.
+     *            the index of the first character in the CharSequence appended
+     *            to the CharArrayWriter.
      * @param end
-     *            The index of the char after the last one in the CharSequence
-     *            appended to the CharArrayWriter.
-     * @return The CharArrayWriter.
+     *            the index of the character after the last one in the
+     *            CharSequence appended to the CharArrayWriter.
+     * @return this CharArrayWriter.
      * @throws IndexOutOfBoundsException
-     *             If start is less than end, end is greater than the length of
-     *             the CharSequence, or start or end is negative.
-     * @see Writer#append(CharSequence, int, int)
+     *             if {@code start < 0}, {@code end < 0}, {@code start > end},
+     *             or if {@code end} is greater than the length of {@code csq}.
      */
     @Override
     public CharArrayWriter append(CharSequence csq, int start, int end) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/CharConversionException.java Fri May  1 08:08:59 2009
@@ -18,26 +18,26 @@
 package java.io;
 
 /**
- * This is the top level class for character conversion exceptions.
+ * The top level class for character conversion exceptions.
  */
 public class CharConversionException extends IOException {
 
     private static final long serialVersionUID = -8680016352018427031L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
-     * 
+     * Constructs a new {@code CharConversionException} with its stack trace
+     * filled in.
      */
     public CharConversionException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code CharConversionException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public CharConversionException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Closeable.java Fri May  1 08:08:59 2009
@@ -17,17 +17,19 @@
 package java.io;
 
 /**
- * Closeable represents the source or destination of some data which can be
- * called its close method to release resources it holds.
+ * Defines an interface for classes that can (or need to) be closed once they
+ * are not used any longer. This usually includes all sorts of
+ * {@link InputStream}s and {@link OutputStream}s. Calling the {@code close}
+ * method releases resources that the object holds.
  */
 public interface Closeable {
 
     /**
-     * Close the object and release any system resources it holds. If the object
-     * has been close, then invoke this method has no effect.
+     * Closes the object and release any system resources it holds. If the
+     * object has already been closed, then invoking this method has no effect.
      * 
      * @throws IOException
-     *             if any error raises when closing the object.
+     *             if any error occurs when closing the object.
      */
     public void close() throws IOException;
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInput.java Fri May  1 08:08:59 2009
@@ -18,107 +18,125 @@
 package java.io;
 
 /**
- * DataInput is an interface which declares methods for reading in typed data
- * from a Stream. Typically, this stream has been written by a class which
- * implements DataOutput. Types that can be read include byte, 16-bit short,
- * 32-bit int, 32-bit float, 64-bit long, 64-bit double, byte strings, and UTF
- * Strings.
- * 
+ * Defines an interface for classes that are able to read typed data from some
+ * source. Typically, this data has been written by a class which implements
+ * {@link DataOutput}. Types that can be read include byte, 16-bit short, 32-bit
+ * int, 32-bit float, 64-bit long, 64-bit double, byte strings, and MUTF-8
+ * strings.
+ *
+ * <h3>MUTF-8 (Modified UTF-8) Encoding</h3>
+ * <p>
+ * When encoding strings as UTF, implementations of {@code DataInput} and
+ * {@code DataOutput} use a slightly modified form of UTF-8, hereafter referred
+ * to as MUTF-8. This form is identical to standard UTF-8, except:
+ * <ul>
+ * <li>Only the one-, two-, and three-byte encodings are used.</li>
+ * <li>Code points in the range <code>U+10000</code> &hellip;
+ * <code>U+10ffff</code> are encoded as a surrogate pair, each of which is
+ * represented as a three-byte encoded value.</li>
+ * <li>The code point <code>U+0000</code> is encoded in two-byte form.</li>
+ * </ul>
+ * <p>
+ * Please refer to <a href="http://unicode.org">The Unicode Standard</a> for
+ * further information about character encoding. MUTF-8 is actually closer to
+ * the (relatively less well-known) encoding <a
+ * href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8 per se.
+ *
  * @see DataInputStream
  * @see RandomAccessFile
  */
 public interface DataInput {
     /**
-     * Reads a boolean from this stream.
-     * 
-     * @return the next boolean value from the source stream.
+     * Reads a boolean.
      * 
+     * @return the next boolean value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeBoolean(boolean)
      */
     public abstract boolean readBoolean() throws IOException;
 
     /**
-     * Reads an 8-bit byte value from this stream.
-     * 
-     * @return the next byte value from the source stream.
+     * Reads an 8-bit byte value.
      * 
+     * @return the next byte value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeByte(int)
      */
     public abstract byte readByte() throws IOException;
 
     /**
-     * Reads a 16-bit character value from this stream.
-     * 
-     * @return the next <code>char</code> value from the source stream.
+     * Reads a 16-bit character value.
      * 
+     * @return the next char value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeChar(int)
      */
     public abstract char readChar() throws IOException;
 
     /**
-     * Reads a 64-bit <code>double</code> value from this stream.
-     * 
-     * @return the next <code>double</code> value from the source stream.
+     * Reads a 64-bit double value.
      * 
+     * @return the next double value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeDouble(double)
      */
     public abstract double readDouble() throws IOException;
 
     /**
-     * Reads a 32-bit <code>float</code> value from this stream.
-     * 
-     * @return the next <code>float</code> value from the source stream.
+     * Reads a 32-bit float value.
      * 
+     * @return the next float value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeFloat(float)
      */
     public abstract float readFloat() throws IOException;
 
     /**
-     * Reads bytes from this stream into the byte array <code>buffer</code>.
-     * This method will block until <code>buffer.length</code> number of bytes
-     * have been read.
+     * Reads bytes into the byte array {@code buffer}. This method will block
+     * until {@code buffer.length} number of bytes have been read.
      * 
      * @param buffer
-     *            the buffer to read bytes into
-     * 
+     *            the buffer to read bytes into.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#write(byte[])
      * @see DataOutput#write(byte[], int, int)
      */
     public abstract void readFully(byte[] buffer) throws IOException;
 
     /**
-     * Read bytes from this stream and stores them in byte array
-     * <code>buffer</code> starting at offset <code>offset</code>. This
-     * method blocks until <code>count</code> number of bytes have been read.
+     * Reads bytes and stores them in the byte array {@code buffer} starting at
+     * offset {@code offset}. This method blocks until {@code count} number of
+     * bytes have been read.
      * 
      * @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.
      * @param count
-     *            the maximum number of bytes to store in <code>buffer</code>.
-     * 
+     *            the maximum number of bytes to store in {@code buffer}.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#write(byte[])
      * @see DataOutput#write(byte[], int, int)
      */
@@ -126,106 +144,102 @@
             throws IOException;
 
     /**
-     * Reads a 32-bit integer value from this stream.
-     * 
-     * @return the next <code>int</code> value from the source stream.
+     * Reads a 32-bit integer value.
      * 
+     * @return the next int value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeInt(int)
      */
     public abstract int readInt() throws IOException;
 
     /**
-     * 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>"\n\r"</code> or end of stream. The <code>String</code> does
-     * not include the newline sequence.
-     * 
-     * @return the contents of the line or null if no characters were read
-     *         before end of stream.
-     * 
+     * Returns a string containing the next line of text available from this
+     * stream. A line is made of zero or more characters followed by {@code
+     * '\n'}, {@code '\r'}, {@code "\r\n"} or the end of the stream. The string
+     * does not include the newline sequence.
+     * 
+     * @return the contents of the line or null if no characters have been read
+     *         before the end of the stream.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
+     *             if an I/O error occurs while reading.
      */
     public abstract String readLine() throws IOException;
 
     /**
-     * Reads a 64-bit <code>long</code> value from this stream.
-     * 
-     * @return the next <code>long</code> value from the source stream.
+     * Reads a 64-bit long value.
      * 
+     * @return the next long value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeLong(long)
      */
     public abstract long readLong() throws IOException;
 
     /**
-     * Reads a 16-bit <code>short</code> value from this stream.
-     * 
-     * @return the next <code>short</code> value from the source stream.
+     * Reads a 16-bit short value.
      * 
+     * @return the next short value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeShort(int)
      */
     public abstract short readShort() throws IOException;
 
     /**
-     * Reads an unsigned 8-bit <code>byte</code> value from this stream and
-     * returns it as an int.
-     * 
-     * @return the next unsigned byte value from the source stream.
+     * Reads an unsigned 8-bit byte value and returns it as an int.
      * 
+     * @return the next unsigned byte value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeByte(int)
      */
     public abstract int readUnsignedByte() throws IOException;
 
     /**
-     * Reads a 16-bit unsigned <code>short</code> value from this stream and
-     * returns it as an int.
-     * 
-     * @return the next unsigned <code>short</code> value from the source
-     *         stream.
+     * Reads a 16-bit unsigned short value and returns it as an int.
      * 
+     * @return the next unsigned short value.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeShort(int)
      */
     public abstract int readUnsignedShort() throws IOException;
 
     /**
-     * Reads a UTF format String from this Stream.
-     * 
-     * @return the next UTF String from the source stream.
+     * Reads a string encoded with {@link DataInput modified UTF-8}.
      * 
+     * @return the next string encoded with {@link DataInput modified UTF-8}.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this stream.
-     * 
+     *             if an I/O error occurs while reading.
      * @see DataOutput#writeUTF(java.lang.String)
      */
     public abstract String readUTF() throws IOException;
 
     /**
-     * Skips <code>count</code> number of bytes in this stream. Subsequent
-     * <code>read()</code>'s will not return these bytes unless
-     * <code>reset()</code> is used.
+     * Skips {@code count} number of bytes. This method will not throw an
+     * {@link EOFException} if the end of the input is reached before
+     * {@code count} bytes where skipped.
      * 
      * @param count
      *            the number of bytes to skip.
      * @return the number of bytes actually skipped.
-     * 
      * @throws IOException
-     *             If a problem occurs reading from this stream.
+     *             if a problem occurs during skipping.
      */
     public abstract int skipBytes(int count) throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataInputStream.java Fri May  1 08:08:59 2009
@@ -21,10 +21,11 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * DataInputStream is a filter class which can read typed data from a Stream.
+ * Wraps an existing {@link InputStream} and reads typed data from it.
  * Typically, this stream has been written by a DataOutputStream. Types that can
  * be read include byte, 16-bit short, 32-bit int, 32-bit float, 64-bit long,
- * 64-bit double, byte strings, and UTF Strings.
+ * 64-bit double, byte strings, and strings encoded in
+ * {@link DataInput modified UTF-8}.
  * 
  * @see DataOutputStream
  */
@@ -33,14 +34,13 @@
     byte[] buff;
 
     /**
-     * Constructs a new DataInputStream on the InputStream <code>in</code>.
-     * All reads can now be filtered through this stream. Note that data read by
-     * this Stream is not in a human readable format and was most likely created
-     * by a DataOutputStream.
+     * Constructs a new DataInputStream on the InputStream {@code in}. All
+     * reads are then filtered through this stream. Note that data read by this
+     * stream is not in a human readable format and was most likely created by a
+     * DataOutputStream.
      * 
      * @param in
-     *            the target InputStream to filter reads on.
-     * 
+     *            the source InputStream the filter reads from.
      * @see DataOutputStream
      * @see RandomAccessFile
      */
@@ -50,16 +50,15 @@
     }
 
     /**
-     * Reads bytes from the source stream into the byte array
-     * <code>buffer</code>. The number of bytes actually read is returned.
+     * Reads bytes from this stream into the byte array {@code buffer}. Returns
+     * the number of bytes that have been read.
      * 
      * @param buffer
-     *            the buffer to read bytes into
-     * @return the number of bytes actually read or -1 if end of stream.
-     * 
+     *            the buffer to read bytes into.
+     * @return the number of bytes that have been read or -1 if the end of the
+     *         stream has been reached.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#write(byte[])
      * @see DataOutput#write(byte[], int, int)
      */
@@ -69,22 +68,22 @@
     }
 
     /**
-     * Read at most <code>length</code> bytes from this DataInputStream 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.
+     * Reads at most {@code length} bytes from this stream and stores them in
+     * the byte array {@code buffer} starting at {@code offset}. Returns the
+     * number of bytes that have been read or -1 if no bytes have been read and
+     * the end of the stream has been reached.
      * 
      * @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>.
-     * @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 that have been read or -1 if the end of the
+     *         stream has been reached.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#write(byte[])
      * @see DataOutput#write(byte[], int, int)
      */
@@ -98,10 +97,11 @@
      * Reads a boolean from this stream.
      * 
      * @return the next boolean value from the source stream.
-     * 
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before one byte
+     *             has been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeBoolean(boolean)
      */
     public final boolean readBoolean() throws IOException {
@@ -116,10 +116,11 @@
      * Reads an 8-bit byte value from this stream.
      * 
      * @return the next byte value from the source stream.
-     * 
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before one byte
+     *             has been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeByte(int)
      */
     public final byte readByte() throws IOException {
@@ -133,11 +134,12 @@
     /**
      * Reads a 16-bit character value from this stream.
      * 
-     * @return the next <code>char</code> value from the source stream.
-     * 
+     * @return the next char value from the source stream.
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before two bytes
+     *             have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeChar(int)
      */
     private int readToBuff(int count) throws IOException {
@@ -160,13 +162,14 @@
     }
 
     /**
-     * Reads a 64-bit <code>double</code> value from this stream.
-     * 
-     * @return the next <code>double</code> value from the source stream.
+     * Reads a 64-bit double value from this stream.
      * 
+     * @return the next double value from the source stream.
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before eight
+     *             bytes have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeDouble(double)
      */
     public final double readDouble() throws IOException {
@@ -174,13 +177,14 @@
     }
 
     /**
-     * Reads a 32-bit <code>float</code> value from this stream.
-     * 
-     * @return the next <code>float</code> value from the source stream.
+     * Reads a 32-bit float value from this stream.
      * 
+     * @return the next float value from the source stream.
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before four
+     *             bytes have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeFloat(float)
      */
     public final float readFloat() throws IOException {
@@ -188,16 +192,17 @@
     }
 
     /**
-     * Reads bytes from this stream into the byte array <code>buffer</code>.
-     * This method will block until <code>buffer.length</code> number of bytes
-     * have been read.
+     * Reads bytes from this stream into the byte array {@code buffer}. This
+     * method will block until {@code buffer.length} number of bytes have been
+     * read.
      * 
      * @param buffer
-     *            to read bytes into
-     * 
+     *            to read bytes into.
+     * @throws EOFException
+     *             if the end of the source stream is reached before enough
+     *             bytes have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#write(byte[])
      * @see DataOutput#write(byte[], int, int)
      */
@@ -206,22 +211,28 @@
     }
 
     /**
-     * Reads bytes from this stream and stores them in the byte array
-     * <code>buffer</code> starting at the position <code>offset</code>.
-     * This method blocks until <code>count</code> bytes have been read.
+     * Reads bytes from this stream and stores them in the byte array {@code
+     * buffer} starting at the position {@code offset}. This method blocks until
+     * {@code length} bytes have been read. If {@code length} is zero, then this
+     * method returns without reading any bytes.
      * 
      * @param buffer
-     *            the byte array into which the data is read
+     *            the byte array into which the data is read.
      * @param offset
-     *            the offset the operation start at
+     *            the offset in {@code buffer} from where to store the bytes
+     *            read.
      * @param length
-     *            the maximum number of bytes to read
-     * 
-     * @throws IOException
-     *             if a problem occurs while reading from this stream
+     *            the maximum number of bytes to read.
      * @throws EOFException
-     *             if reaches the end of the stream before enough bytes have
-     *             been read
+     *             if the end of the source stream is reached before enough
+     *             bytes have been read.
+     * @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 a problem occurs while reading from this stream.
+     * @throws NullPointerException
+     *             if {@code buffer} or the source stream are null.
      * @see java.io.DataInput#readFully(byte[], int, int)
      */
     public final void readFully(byte[] buffer, int offset, int length)
@@ -254,11 +265,12 @@
     /**
      * Reads a 32-bit integer value from this stream.
      * 
-     * @return the next <code>int</code> value from the source stream.
-     * 
+     * @return the next int value from the source stream.
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before four
+     *             bytes have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeInt(int)
      */
     public final int readInt() throws IOException {
@@ -270,20 +282,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>"\n\r"</code> or end of stream. The <code>String</code> does
-     * not include the newline sequence.
-     * 
-     * @return the contents of the line or null if no characters were read
-     *         before end of stream.
+     * Returns a string that contains the next line of text available from the
+     * source stream. A line is represented by zero or more characters followed
+     * by {@code '\n'}, {@code '\r'}, {@code "\r\n"} or the end of the stream.
+     * The string does not include the newline sequence.
      * 
+     * @return the contents of the line or {@code null} if no characters were
+     *         read before the end of the source stream has been reached.
      * @throws IOException
-     *             If the DataInputStream is already closed or some other IO
-     *             error occurs.
-     * 
-     * @deprecated Use BufferedReader
+     *             if a problem occurs while reading from this stream.
+     * @deprecated Use {@link BufferedReader}
      */
     @Deprecated
     public final String readLine() throws IOException {
@@ -321,13 +329,14 @@
     }
 
     /**
-     * Reads a 64-bit <code>long</code> value from this stream.
-     * 
-     * @return the next <code>long</code> value from the source stream.
+     * Reads a 64-bit long value from this stream.
      * 
+     * @return the next long value from the source stream.
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before eight
+     *             bytes have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeLong(long)
      */
     public final long readLong() throws IOException {
@@ -343,13 +352,14 @@
     }
 
     /**
-     * Reads a 16-bit <code>short</code> value from this stream.
-     * 
-     * @return the next <code>short</code> value from the source stream.
+     * Reads a 16-bit short value from this stream.
      * 
+     * @return the next short value from the source stream.
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before two bytes
+     *             have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeShort(int)
      */
     public final short readShort() throws IOException {
@@ -360,14 +370,15 @@
     }
 
     /**
-     * Reads an unsigned 8-bit <code>byte</code> value from this stream and
-     * returns it as an int.
+     * Reads an unsigned 8-bit byte value from this stream and returns it as an
+     * int.
      * 
      * @return the next unsigned byte value from the source stream.
-     * 
+     * @throws EOFException
+     *             if the end of the filtered stream has been reached before one
+     *             byte has been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeByte(int)
      */
     public final int readUnsignedByte() throws IOException {
@@ -379,15 +390,15 @@
     }
 
     /**
-     * Reads a 16-bit unsigned <code>short</code> value from this stream and
-     * returns it as an int.
-     * 
-     * @return the next unsigned <code>short</code> value from the source
-     *         stream.
+     * Reads a 16-bit unsigned short value from this stream and returns it as an
+     * int.
      * 
+     * @return the next unsigned short value from the source stream.
+     * @throws EOFException
+     *             if the end of the filtered stream is reached before two bytes
+     *             have been read.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeShort(int)
      */
     public final int readUnsignedShort() throws IOException {
@@ -398,13 +409,15 @@
     }
 
     /**
-     * Reads a UTF format String from this Stream.
-     * 
-     * @return the next UTF String from the source stream.
+     * Reads an string encoded in {@link DataInput modified UTF-8} from this
+     * stream.
      * 
+     * @return the next {@link DataInput MUTF-8} encoded string read from the
+     *         source stream.
+     * @throws EOFException if the end of the input is reached before the read
+     *         request can be satisfied.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
+     *             if a problem occurs while reading from this stream.
      * @see DataOutput#writeUTF(java.lang.String)
      */
     public final String readUTF() throws IOException {
@@ -425,33 +438,35 @@
     }
 
     /**
-     * Reads a UTF format String from the DataInput Stream <code>in</code>.
+     * Reads a string encoded in {@link DataInput modified UTF-8} from the
+     * {@code DataInput} stream {@code in}.
      * 
      * @param in
-     *            the input stream to read from
-     * @return the next UTF String from the source stream.
-     * 
+     *            the input stream to read from.
+     * @return the next {@link DataInput MUTF-8} encoded string from the source
+     *         stream.
      * @throws IOException
-     *             If a problem occurs reading from this DataInputStream.
-     * 
-     * @see DataOutput#writeUTF(java.lang.String)
+     *             if a problem occurs while reading from this stream.
+     * @see DataOutputStream#writeUTF(java.lang.String)
      */
     public static final String readUTF(DataInput in) throws IOException {
         return decodeUTF(in.readUnsignedShort(), in);
     }
 
     /**
-     * Skips <code>count</code> number of bytes in this stream. Subsequent
-     * <code>read()</code>'s will not return these bytes unless
-     * <code>reset()</code> is used.
+     * Skips {@code count} number of bytes in this stream. Subsequent {@code
+     * read()}s will not return these bytes unless {@code reset()} is used.
      * 
+     * This method will not throw an {@link EOFException} if the end of the
+     * input is reached before {@code count} bytes where 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 a problem occurs during skipping.
+     * @see #mark(int)
+     * @see #reset()
      */
     public final int skipBytes(int count) throws IOException {
         int skipped = 0;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutput.java Fri May  1 08:08:59 2009
@@ -18,10 +18,11 @@
 package java.io;
 
 /**
- * DataOutput is an interface which declares methods for writing typed data to a
- * Stream. Typically, this stream can be read in by a class which implements
+ * Defines an interface for classes that are able to write typed data to some
+ * target. Typically, this data can be read in by a class which implements
  * DataInput. Types that can be written include byte, 16-bit short, 32-bit int,
- * 32-bit float, 64-bit long, 64-bit double, byte strings, and UTF Strings.
+ * 32-bit float, 64-bit long, 64-bit double, byte strings, and {@link DataInput
+ * MUTF-8} encoded strings.
  * 
  * @see DataOutputStream
  * @see RandomAccessFile
@@ -29,35 +30,30 @@
 public interface DataOutput {
 
     /**
-     * Writes the entire contents of the byte array <code>buffer</code> to the
-     * OutputStream.
+     * Writes the entire contents of the byte array {@code buffer} to this
+     * stream.
      * 
      * @param buffer
-     *            the buffer to be written
-     * 
+     *            the buffer to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readFully(byte[])
      * @see DataInput#readFully(byte[], int, int)
      */
-    public abstract void write(byte buffer[]) throws IOException;
+    public abstract void write(byte[] buffer) throws IOException;
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at offset <code>index</code> to the
-     * OutputStream.
+     * Writes {@code count} bytes from the byte array {@code buffer} starting at
+     * offset {@code index}.
      * 
      * @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
-     * 
+     *            the number of bytes from the {@code buffer} to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readFully(byte[])
      * @see DataInput#readFully(byte[], int, int)
      */
@@ -65,170 +61,143 @@
             throws IOException;
 
     /**
-     * Writes the specified <code>byte</code> to the OutputStream.
+     * Writes the specified 8-bit byte.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
+     *            the byte to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readByte()
      */
     public abstract void write(int oneByte) throws IOException;
 
     /**
-     * Writes a boolean to this output stream.
+     * Writes the specified boolean.
      * 
      * @param val
-     *            the boolean value to write to the OutputStream
-     * 
+     *            the boolean value to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readBoolean()
      */
     public abstract void writeBoolean(boolean val) throws IOException;
 
     /**
-     * Writes a 8-bit byte to this output stream.
+     * Writes the specified 8-bit byte.
      * 
      * @param val
-     *            the byte value to write to the OutputStream
-     * 
+     *            the byte value to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readByte()
      * @see DataInput#readUnsignedByte()
      */
     public abstract void writeByte(int val) throws IOException;
 
     /**
-     * Writes the low order 8-bit bytes from a String to this output stream.
+     * Writes the low order 8-bit bytes from the specified string.
      * 
      * @param str
-     *            the String containing the bytes to write to the OutputStream
-     * 
+     *            the string containing the bytes to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readFully(byte[])
      * @see DataInput#readFully(byte[],int,int)
      */
     public abstract void writeBytes(String str) throws IOException;
 
     /**
-     * Writes the specified 16-bit character to the OutputStream. Only the lower
-     * 2 bytes are written with the higher of the 2 bytes written first. This
-     * represents the Unicode value of val.
-     * 
-     * @param oneByte
-     *            the character to be written
+     * Writes the specified 16-bit character. Only the two least significant
+     * bytes of the integer {@code oneByte} are written, with the higher one
+     * written first. This represents the Unicode value of the char.
      * 
+     * @param val
+     *            the character to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readChar()
      */
-    public abstract void writeChar(int oneByte) throws IOException;
+    public abstract void writeChar(int val) throws IOException;
 
     /**
-     * Writes the specified 16-bit characters contained in str to the
-     * OutputStream. Only the lower 2 bytes of each character are written with
-     * the higher of the 2 bytes written first. This represents the Unicode
-     * value of each character in str.
+     * Writes the 16-bit characters contained in {@code str}.
      * 
      * @param str
-     *            the String whose characters are to be written.
-     * 
+     *            the string that contains the characters to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readChar()
      */
     public abstract void writeChars(String str) throws IOException;
 
     /**
-     * Writes a 64-bit double to this output stream. The resulting output is the
-     * 8 bytes resulting from calling Double.doubleToLongBits().
+     * Writes the specified 64-bit double. The resulting output is the eight
+     * bytes returned by {@link Double#doubleToLongBits(double)}.
      * 
      * @param val
-     *            the double to be written.
-     * 
+     *            the double to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readDouble()
      */
     public abstract void writeDouble(double val) throws IOException;
 
     /**
-     * Writes a 32-bit float to this output stream. The resulting output is the
-     * 4 bytes resulting from calling Float.floatToIntBits().
+     * Writes the specified 32-bit float. The resulting output is the four bytes
+     * returned by {@link Float#floatToIntBits(float)}.
      * 
      * @param val
-     *            the float to be written.
-     * 
+     *            the float to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readFloat()
      */
     public abstract void writeFloat(float val) throws IOException;
 
     /**
-     * Writes a 32-bit int to this output stream. The resulting output is the 4
-     * bytes, highest order first, of val.
+     * Writes the specified 32-bit int. The resulting output is the four bytes,
+     * highest order first, of {@code val}.
      * 
      * @param val
-     *            the int to be written.
-     * 
+     *            the int to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readInt()
      */
     public abstract void writeInt(int val) throws IOException;
 
     /**
-     * Writes a 64-bit long to this output stream. The resulting output is the 8
-     * bytes, highest order first, of val.
+     * Writes the specified 64-bit long. The resulting output is the eight
+     * bytes, highest order first, of {@code val}.
      * 
      * @param val
-     *            the long to be written.
-     * 
+     *            the long to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readLong()
      */
     public abstract void writeLong(long val) throws IOException;
 
     /**
-     * Writes the specified 16-bit short to the OutputStream. Only the lower 2
-     * bytes are written with the higher of the 2 bytes written first.
+     * Writes the specified 16-bit short. Only the lower two bytes of {@code
+     * val} are written with the higher one written first.
      * 
      * @param val
-     *            the short to be written
-     * 
+     *            the short to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readShort()
      * @see DataInput#readUnsignedShort()
      */
     public abstract void writeShort(int val) throws IOException;
 
     /**
-     * Writes the specified String out in UTF format.
+     * Writes the specified string encoded in {@link DataInput modified UTF-8}.
      * 
      * @param str
-     *            the String to be written in UTF format.
-     * 
+     *            the string to write encoded in {@link DataInput modified UTF-8}.
      * @throws IOException
-     *             If an error occurs attempting to write to this stream.
-     * 
+     *             if an I/O error occurs while writing.
      * @see DataInput#readUTF()
      */
     public abstract void writeUTF(String str) throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/DataOutputStream.java Fri May  1 08:08:59 2009
@@ -20,27 +20,29 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * DataOutputStream is a filter class which can write typed data to a Stream.
- * Typically, this stream can be read in by a DataInputStream. Types that can be
+ * Wraps an existing {@link OutputStream} and writes typed data to it.
+ * Typically, this stream can be read in by DataInputStream. Types that can be
  * written include byte, 16-bit short, 32-bit int, 32-bit float, 64-bit long,
- * 64-bit double, byte strings, and UTF Strings.
+ * 64-bit double, byte strings, and {@link DataInput MUTF-8} encoded strings.
  * 
  * @see DataInputStream
  */
 public class DataOutputStream extends FilterOutputStream implements DataOutput {
 
-    /** The number of bytes written out so far */
+    /**
+     * The number of bytes written out so far.
+     */
     protected int written;
     byte buff[];
 
     /**
-     * Constructs a new DataOutputStream on the OutputStream <code>out</code>.
-     * All writes can now be filtered through this stream. Note that data
-     * written by this Stream is not in a human readable format but can be
-     * reconstructed by using a DataInputStream on the resulting output.
+     * Constructs a new {@code DataOutputStream} on the {@code OutputStream}
+     * {@code out}. Note that data written by this stream is not in a human
+     * readable form but can be reconstructed by using a {@link DataInputStream}
+     * on the resulting output.
      * 
      * @param out
-     *            the target OutputStream to filter writes on.
+     *            the target stream for writing.
      */
     public DataOutputStream(OutputStream out) {
         super(out);
@@ -48,11 +50,11 @@
     }
 
     /**
-     * Flush this DataOutputStream to ensure all pending data is sent out to the
-     * target OutputStream. This implementation flushes the target OutputStream.
+     * Flushes this stream to ensure all pending data is sent out to the target
+     * stream. This implementation then also flushes the target stream.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this DataOutputStream.
+     *             if an error occurs attempting to flush this stream.
      */
     @Override
     public void flush() throws IOException {
@@ -60,9 +62,9 @@
     }
 
     /**
-     * Answers the total number of bytes written to this stream thus far.
+     * Returns the total number of bytes written to the target stream so far.
      * 
-     * @return the number of bytes written to this DataOutputStream.
+     * @return the number of bytes written to the target stream.
      */
     public final int size() {
         if (written < 0) {
@@ -72,23 +74,21 @@
     }
 
     /**
-     * Writes <code>count</code> <code>bytes</code> from the byte array
-     * <code>buffer</code> starting at offset <code>index</code> to the
-     * 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 to the target stream.
      * @param offset
-     *            offset in buffer to get bytes
+     *            the index of the first byte in {@code buffer} to write.
      * @param count
-     *            number of bytes in buffer to write
-     * 
+     *            the number of bytes from the {@code buffer} to write.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readFully(byte[])
-     * @see DataInput#readFully(byte[], int, int)
+     *             if an error occurs while writing to the target stream.
+     * @throws NullPointerException
+     *             if {@code buffer} is {@code null}.
+     * @see DataInputStream#readFully(byte[])
+     * @see DataInputStream#readFully(byte[], int, int)
      */
     @Override
     public void write(byte buffer[], int offset, int count) throws IOException {
@@ -100,16 +100,14 @@
     }
 
     /**
-     * Writes the specified <code>byte</code> to the OutputStream.
+     * Writes a byte to the target stream. Only the least significant byte of
+     * the integer {@code oneByte} is written.
      * 
      * @param oneByte
-     *            the byte to be written
-     * 
+     *            the byte to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readByte()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readByte()
      */
     @Override
     public void write(int oneByte) throws IOException {
@@ -118,16 +116,13 @@
     }
 
     /**
-     * Writes a boolean to this output stream.
+     * Writes a boolean to the target stream.
      * 
      * @param val
-     *            the boolean value to write to the OutputStream
-     * 
+     *            the boolean value to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readBoolean()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readBoolean()
      */
     public final void writeBoolean(boolean val) throws IOException {
         out.write(val ? 1 : 0);
@@ -135,17 +130,15 @@
     }
 
     /**
-     * Writes a 8-bit byte to this output stream.
+     * Writes an 8-bit byte to the target stream. Only the least significant
+     * byte of the integer {@code val} is written.
      * 
      * @param val
-     *            the byte value to write to the OutputStream
-     * 
+     *            the byte value to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readByte()
-     * @see DataInput#readUnsignedByte()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readByte()
+     * @see DataInputStream#readUnsignedByte()
      */
     public final void writeByte(int val) throws IOException {
         out.write(val);
@@ -153,17 +146,14 @@
     }
 
     /**
-     * Writes the low order 8-bit bytes from a String to this output stream.
+     * Writes the low order bytes from a string to the target stream.
      * 
      * @param str
-     *            the String containing the bytes to write to the OutputStream
-     * 
+     *            the string containing the bytes to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readFully(byte[])
-     * @see DataInput#readFully(byte[],int,int)
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readFully(byte[])
+     * @see DataInputStream#readFully(byte[],int,int)
      */
     public final void writeBytes(String str) throws IOException {
         if (str.length() == 0) {
@@ -178,18 +168,15 @@
     }
 
     /**
-     * Writes the specified 16-bit character to the OutputStream. Only the lower
-     * 2 bytes are written with the higher of the 2 bytes written first. This
-     * represents the Unicode value of val.
+     * Writes a 16-bit character to the target stream. Only the two lower bytes
+     * of the integer {@code val} are written, with the higher one written
+     * first. This corresponds to the Unicode value of {@code val}.
      * 
      * @param val
-     *            the character to be written
-     * 
+     *            the character to write to the target stream
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readChar()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readChar()
      */
     public final void writeChar(int val) throws IOException {
         buff[0] = (byte) (val >> 8);
@@ -199,19 +186,15 @@
     }
 
     /**
-     * Writes the specified 16-bit characters contained in str to the
-     * OutputStream. Only the lower 2 bytes of each character are written with
-     * the higher of the 2 bytes written first. This represents the Unicode
-     * value of each character in str.
+     * Writes the 16-bit characters contained in {@code str} to the target
+     * stream.
      * 
      * @param str
-     *            the String whose characters are to be written.
-     * 
+     *            the string that contains the characters to write to this
+     *            stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readChar()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readChar()
      */
     public final void writeChars(String str) throws IOException {
         byte newBytes[] = new byte[str.length() * 2];
@@ -225,51 +208,42 @@
     }
 
     /**
-     * Writes a 64-bit double to this output stream. The resulting output is the
-     * 8 bytes resulting from calling Double.doubleToLongBits().
+     * Writes a 64-bit double to the target stream. The resulting output is the
+     * eight bytes resulting from calling Double.doubleToLongBits().
      * 
      * @param val
-     *            the double to be written.
-     * 
+     *            the double to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readDouble()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readDouble()
      */
     public final void writeDouble(double val) throws IOException {
         writeLong(Double.doubleToLongBits(val));
     }
 
     /**
-     * Writes a 32-bit float to this output stream. The resulting output is the
-     * 4 bytes resulting from calling Float.floatToIntBits().
+     * Writes a 32-bit float to the target stream. The resulting output is the
+     * four bytes resulting from calling Float.floatToIntBits().
      * 
      * @param val
-     *            the float to be written.
-     * 
+     *            the float to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readFloat()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readFloat()
      */
     public final void writeFloat(float val) throws IOException {
         writeInt(Float.floatToIntBits(val));
     }
 
     /**
-     * Writes a 32-bit int to this output stream. The resulting output is the 4
-     * bytes, highest order first, of val.
+     * Writes a 32-bit int to the target stream. The resulting output is the
+     * four bytes, highest order first, of {@code val}.
      * 
      * @param val
-     *            the int to be written.
-     * 
+     *            the int to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readInt()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readInt()
      */
     public final void writeInt(int val) throws IOException {
         buff[0] = (byte) (val >> 24);
@@ -281,17 +255,14 @@
     }
 
     /**
-     * Writes a 64-bit long to this output stream. The resulting output is the 8
-     * bytes, highest order first, of val.
+     * Writes a 64-bit long to the target stream. The resulting output is the
+     * eight bytes, highest order first, of {@code val}.
      * 
      * @param val
-     *            the long to be written.
-     * 
+     *            the long to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readLong()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readLong()
      */
     public final void writeLong(long val) throws IOException {
         buff[0] = (byte) (val >> 56);
@@ -307,18 +278,16 @@
     }
 
     /**
-     * Writes the specified 16-bit short to the OutputStream. Only the lower 2
-     * bytes are written with the higher of the 2 bytes written first.
+     * Writes the specified 16-bit short to the target stream. Only the lower
+     * two bytes of the integer {@code val} are written, with the higher one
+     * written first.
      * 
      * @param val
-     *            the short to be written
-     * 
+     *            the short to write to the target stream.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readShort()
-     * @see DataInput#readUnsignedShort()
+     *             if an error occurs while writing to the target stream.
+     * @see DataInputStream#readShort()
+     * @see DataInputStream#readUnsignedShort()
      */
     public final void writeShort(int val) throws IOException {
         buff[0] = (byte) (val >> 8);
@@ -328,16 +297,17 @@
     }
 
     /**
-     * Writes the specified String out in UTF format.
+     * Writes the specified encoded in {@link DataInput modified UTF-8} to this
+     * stream.
      * 
      * @param str
-     *            the String to be written in UTF format.
-     * 
+     *            the string to write to the target stream encoded in
+     *            {@link DataInput modified UTF-8}.
      * @throws IOException
-     *             If an error occurs attempting to write to this
-     *             DataOutputStream.
-     * 
-     * @see DataInput#readUTF()
+     *             if an error occurs while writing to the target stream.
+     * @throws UTFDataFormatException
+     *             if the encoded string is longer than 65535 bytes.
+     * @see DataInputStream#readUTF()
      */
     public final void writeUTF(String str) throws IOException {
         long utfCount = countUTFBytes(str);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/EOFException.java Fri May  1 08:08:59 2009
@@ -18,27 +18,26 @@
 package java.io;
 
 /**
- * This End Of File (EOF) exception is thrown when a program encounters the end
- * of a file or stream during an operation.
+ * Thrown when a program encounters the end of a file or stream during an input
+ * operation.
  */
 public class EOFException extends IOException {
 
     private static final long serialVersionUID = 6433858223774886977L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
-     * 
+     * Constructs a new {@code EOFException} with its stack trace filled in.
      */
     public EOFException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code EOFException} with its stack trace and detail
+     * message filled in.
      * 
      * @param detailMessage
-     *            The detail message for the exception.
+     *            the detail message for this exception.
      */
     public EOFException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Externalizable.java Fri May  1 08:08:59 2009
@@ -18,21 +18,19 @@
 package java.io;
 
 /**
- * Objects that want to be serialized/deserialized using
- * ObjectOutputStream/ObjectInputStream but defining their own byte
- * representation should implement this interface.
+ * Defines an interface for classes that want to be serializable, but have their
+ * own binary representation.
  */
 public interface Externalizable extends Serializable {
     /**
-     * Reads the next object from the ObjectInput <code>input</code>
+     * Reads the next object from the ObjectInput <code>input</code>.
      * 
      * @param input
-     *            the ObjectInput from which the next object is read
-     * 
+     *            the ObjectInput from which the next object is read.
      * @throws IOException
-     *             If an error occurs attempting to read from this ObjectInput.
+     *             if an error occurs attempting to read from {@code input}.
      * @throws ClassNotFoundException
-     *             If the class of the instance being loaded cannot be found
+     *             if the class of the instance being loaded cannot be found.
      */
     public void readExternal(ObjectInput input) throws IOException,
             ClassNotFoundException;
@@ -41,10 +39,9 @@
      * Writes the receiver to the ObjectOutput <code>output</code>.
      * 
      * @param output
-     *            an ObjectOutput where to write the object
-     * 
+     *            the ObjectOutput to write the object to.
      * @throws IOException
-     *             If an error occurs attempting to write to the ObjectOutput.
+     *             if an error occurs attempting to write to {@code output}.
      */
     public void writeExternal(ObjectOutput output) throws IOException;
 }



Mime
View raw message