harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770573 [10/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/StringBufferInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringBufferInputStream.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringBufferInputStream.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringBufferInputStream.java
Fri May  1 08:08:59 2009
@@ -20,33 +20,37 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * StringBufferInputStream is a class for to allow a String to be used as an
- * InputStream.
+ * A specialized {@link InputStream} that reads bytes from a {@code String} in
+ * a sequential manner.
  * 
- * @deprecated Use StringReader
+ * @deprecated Use {@link StringReader}
  */
 @Deprecated
 public class StringBufferInputStream extends InputStream {
     /**
-     * The String containing the data to read.
+     * The source string containing the data to read.
      */
     protected String buffer;
 
     /**
-     * The total number of characters inside the buffer.
+     * The total number of characters in the source string.
      */
     protected int count;
 
     /**
-     * The current position within the String buffer.
+     * The current position within the source string.
      */
     protected int pos;
 
     /**
-     * Constructs a new StringBufferInputStream on the String <code>str</code>.
+     * Construct a new {@code StringBufferInputStream} with {@code str} as
+     * source. The size of the stream is set to the {@code length()} of the
+     * string.
      * 
      * @param str
-     *            the String to read characters from.
+     *            the source string for this stream.
+     * @throws NullPointerException
+     *             if {@code str} is {@code null}.
      */
     public StringBufferInputStream(String str) {
         if (str == null) {
@@ -57,11 +61,10 @@
     }
 
     /**
-     * Answers an int representing then number of characters that are available
-     * to read.
-     * 
-     * @return the number of characters available.
+     * Returns the number of bytes that are available before this stream will
+     * block.
      * 
+     * @return the number of bytes available before blocking.
      */
     @Override
     public synchronized int available() {
@@ -69,11 +72,12 @@
     }
 
     /**
-     * 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.
+     * Reads a single byte from the source string and returns it as an integer
+     * in the range from 0 to 255. Returns -1 if the end of the source string
+     * has been reached.
      * 
-     * @return the byte read or -1 if end of stream.
+     * @return the byte read or -1 if the end of the source string has been
+     *         reached.
      */
     @Override
     public synchronized int read() {
@@ -81,18 +85,24 @@
     }
 
     /**
-     * Reads at most <code>length</code> bytes from this InputStream 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 the source string 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 b} to store the bytes read from
+     *            this stream.
      * @param length
-     *            the maximum number of bytes to store in <code>b</code>.
-     * @return the number of bytes actually read or -1 if end of stream.
+     *            the maximum number of bytes to store in {@code b}.
+     * @return the number of bytes actually read or -1 if the end of the source
+     *         string 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 NullPointerException
+     *             if {@code b} is {@code null}.
      */
     @Override
     public synchronized int read(byte b[], int offset, int length) {
@@ -122,9 +132,7 @@
     }
 
     /**
-     * Reset this InputStream to position 0. Reads/Skips will now take place
-     * from this position.
-     * 
+     * Resets this stream to the beginning of the source string.
      */
     @Override
     public synchronized void reset() {
@@ -132,9 +140,10 @@
     }
 
     /**
-     * Skips <code>count</code> number of characters in this InputStream.
-     * Subsequent <code>read()</code>'s will not return these characters
-     * unless <code>reset()</code> is used.
+     * Skips {@code n} characters in the source string. It does nothing and
+     * returns 0 if {@code n} is negative. Less than {@code n} characters are
+     * skipped if the end of the source string is reached before the operation
+     * completes.
      * 
      * @param n
      *            the number of characters to skip.

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringReader.java Fri
May  1 08:08:59 2009
@@ -20,7 +20,8 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * StringReader is used as a character input stream on a String.
+ * A specialized {@link Reader} that reads characters from a {@code String} in
+ * a sequential manner.
  * 
  * @see StringWriter
  */
@@ -34,12 +35,12 @@
     private int count;
 
     /**
-     * Construct a StringReader on the String <code>str</code>. The size of
-     * the reader is set to the <code>length()</code> of the String and the
-     * Object to synchronize access through is set to <code>str</code>.
+     * Construct a new {@code StringReader} with {@code str} as source. The size
+     * of the reader is set to the {@code length()} of the string and the Object
+     * to synchronize access through is set to {@code str}.
      * 
      * @param str
-     *            the String to filter reads on.
+     *            the source string for this reader.
      */
     public StringReader(String str) {
         super();
@@ -48,9 +49,9 @@
     }
 
     /**
-     * This method closes this StringReader. Once it is closed, you can no
-     * longer read from it. Only the first invocation of this method has any
-     * effect.
+     * Closes this reader. Once it is closed, read operations on this reader
+     * will throw an {@code IOException}. Only the first invocation of this
+     * method has any effect.
      */
     @Override
     public void close() {
@@ -58,24 +59,27 @@
     }
 
     /**
-     * Answer a boolean indicating whether or not this StringReader is closed.
+     * Returns a boolean indicating whether this reader is closed.
      * 
-     * @return <code>true</code> if closed, otherwise <code>false</code>.
+     * @return {@code true} if closed, otherwise {@code false}.
      */
     private boolean isClosed() {
         return str == null;
     }
 
     /**
-     * Set a Mark position in this Reader. The parameter <code>readLimit</code>
-     * is ignored for StringReaders. Sending reset() will reposition the reader
-     * back to the marked position provided the mark has not been invalidated.
+     * Sets a mark position in this reader. The parameter {@code readLimit} is
+     * ignored for this class. Calling {@code reset()} will reposition the
+     * reader back to the marked position.
      * 
      * @param readLimit
-     *            ignored for StringReaders.
-     * 
+     *            ignored for {@code StringReader} instances.
+     * @throws IllegalArgumentException
+     *             if {@code readLimit < 0}.
      * @throws IOException
-     *             If an error occurs attempting mark this StringReader.
+     *             if this reader is closed.
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public void mark(int readLimit) throws IOException {
@@ -92,12 +96,10 @@
     }
 
     /**
-     * Answers a boolean indicating whether or not this StringReader supports
-     * mark() and reset(). This method always returns true.
+     * Indicates whether this reader supports the {@code mark()} and {@code
+     * reset()} methods. This implementation returns {@code true}.
      * 
-     * @return <code>true</code> if mark() and reset() are supported,
-     *         <code>false</code> otherwise. This implementation always
-     *         returns <code>true</code>.
+     * @return always {@code true}.
      */
     @Override
     public boolean markSupported() {
@@ -105,14 +107,14 @@
     }
 
     /**
-     * Reads a single character from this StringReader and returns the result as
-     * an int. The 2 higher-order bytes are set to 0. If the end of reader was
-     * encountered then return -1.
-     * 
-     * @return the character read or -1 if end of reader.
+     * Reads a single character from the source string and returns it as an
+     * integer with the two higher-order bytes set to 0. Returns -1 if the end
+     * of the source string has been reached.
      * 
+     * @return the character read or -1 if the end of the source string has been
+     *         reached.
      * @throws IOException
-     *             If the StringReader is already closed.
+     *             if this reader is closed.
      */
     @Override
     public int read() throws IOException {
@@ -127,10 +129,26 @@
         }
     }
 
-    /*
-     * (non-Javadoc)
-     * 
-     * @see java.io.Reader#read(char[], int, int)
+    /**
+     * Reads at most {@code len} characters from the source string and stores
+     * them at {@code offset} in the character array {@code buf}. Returns the
+     * number of characters actually read or -1 if the end of the source string
+     * has been reached.
+     * 
+     * @param buf
+     *            the character array to store the characters read.
+     * @param offset
+     *            the initial position in {@code buffer} to store the characters
+     *            read from this reader.
+     * @param len
+     *            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 len < 0}, or if
+     *             {@code offset + len} is greater than the size of {@code buf}.
+     * @throws IOException
+     *             if this reader is closed.
      */
     @Override
     public int read(char buf[], int offset, int len) throws IOException {
@@ -158,19 +176,14 @@
     }
 
     /**
-     * Answers a <code>boolean</code> indicating whether or not this
-     * StringReader is ready to be read without blocking. If the result is
-     * <code>true</code>, the next <code>read()</code> will not block.
If
-     * the result is <code>false</code> this Reader may or may not block when
-     * <code>read()</code> is sent. The implementation in StringReader always
-     * returns <code>true</code> even when it has been closed.
-     * 
-     * @return <code>true</code> if the receiver will not block when
-     *         <code>read()</code> is called, <code>false</code>
if unknown
-     *         or blocking will occur.
+     * Indicates whether this reader is ready to be read without blocking. This
+     * implementation always returns {@code true}.
      * 
+     * @return always {@code true}.
      * @throws IOException
-     *             If an IO error occurs.
+     *             if this reader is closed.
+     * @see #read()
+     * @see #read(char[], int, int)
      */
     @Override
     public boolean ready() throws IOException {
@@ -183,13 +196,15 @@
     }
 
     /**
-     * Reset this StringReader's position to the last <code>mark()</code>
-     * location. Invocations of <code>read()/skip()</code> will occur from
-     * this new location. If this Reader was not marked, the StringReader is
-     * reset to the beginning of the String.
+     * Resets this reader's position to the last {@code mark()} location.
+     * Invocations of {@code read()} and {@code skip()} will occur from this new
+     * location. If this reader has not been marked, it is reset to the
+     * beginning of the source string.
      * 
      * @throws IOException
-     *             If this StringReader has already been closed.
+     *             if this reader is closed.
+     * @see #mark(int)
+     * @see #markSupported()
      */
     @Override
     public void reset() throws IOException {
@@ -201,10 +216,19 @@
         }
     }
 
-    /*
-     * (non-Javadoc)
-     * 
-     * @see java.io.Reader#skip(long)
+    /**
+     * Skips {@code amount} characters in the source string. Subsequent calls of
+     * {@code read} methods will not return these characters unless {@code
+     * reset()} is used.
+     * 
+     * @param ns
+     *            the maximum number of characters to skip.
+     * @return the number of characters actually skipped or 0 if {@code ns < 0}.
+     * @throws IOException
+     *             if this reader is closed.
+     * @see #mark(int)
+     * @see #markSupported()
+     * @see #reset()
      */
     @Override
     public long skip(long ns) throws IOException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/StringWriter.java Fri
May  1 08:08:59 2009
@@ -18,9 +18,10 @@
 package java.io;
 
 /**
- * StringWriter is an class for writing Character Streams to a StringBuffer. The
- * characters written can then be returned as a String. This is used for
- * capturing output sent to a Writer by substituting a StringWriter.
+ * A specialized {@link Writer} that writes characters to a {@code StringBuffer}
+ * in a sequential manner, appending them in the process. The result can later
+ * be queried using the {@link #StringWriter(int)} or {@link #toString()}
+ * methods.
  * 
  * @see StringReader
  */
@@ -29,9 +30,10 @@
     private StringBuffer buf;
 
     /**
-     * Constructs a new StringWriter which has a StringBuffer allocated with the
-     * default size of 16 characters. The StringBuffer is also the
-     * <code>lock</code> used to synchronize access to this Writer.
+     * Constructs a new {@code StringWriter} which has a {@link StringBuffer}
+     * allocated with the default size of 16 characters. The {@code
+     * StringBuffer} is also the {@code lock} used to synchronize access to this
+     * writer.
      */
     public StringWriter() {
         super();
@@ -40,12 +42,13 @@
     }
 
     /**
-     * Constructs a new StringWriter which has a StringBuffer allocated with the
-     * size of <code>initialSize</code> characters. The StringBuffer is also
-     * the <code>lock</code> used to synchronize access to this Writer.
+     * Constructs a new {@code StringWriter} which has a {@link StringBuffer}
+     * allocated with a size of {@code initialSize} characters. The {@code
+     * StringBuffer} is also the {@code lock} used to synchronize access to this
+     * writer.
      * 
      * @param initialSize
-     *            the intial number of characters
+     *            the intial size of the target string buffer.
      */
     public StringWriter(int initialSize) {
         if (initialSize < 0) {
@@ -56,11 +59,12 @@
     }
 
     /**
-     * Close this Writer. This is the concrete implementation required. This
-     * particular implementation does nothing.
+     * Calling this method has no effect. In contrast to most {@code Writer} subclasses,
+     * the other methods in {@code StringWriter} do not throw an {@code IOException} if
+     * {@code close()} has been called.
      * 
      * @throws IOException
-     *             If an IO error occurs closing this StringWriter.
+     *             if an error occurs while closing this writer.
      */
     @Override
     public void close() throws IOException {
@@ -68,8 +72,7 @@
     }
 
     /**
-     * Flush this Writer. This is the concrete implementation required. This
-     * particular implementation does nothing.
+     * Calling this method has no effect.
      */
     @Override
     public void flush() {
@@ -77,22 +80,19 @@
     }
 
     /**
-     * Answer the contents of this StringWriter as a StringBuffer. Any changes
-     * made to the StringBuffer by the receiver or the caller are reflected in
-     * this StringWriter.
+     * Gets a reference to this writer's internal {@link StringBuffer}. Any
+     * changes made to the returned buffer are reflected in this writer.
      * 
-     * @return this StringWriters local StringBuffer.
+     * @return a reference to this writer's internal {@code StringBuffer}.
      */
     public StringBuffer getBuffer() {
         return buf;
     }
 
     /**
-     * Answer the contents of this StringWriter as a String. Any changes made to
-     * the StringBuffer by the receiver after returning will not be reflected in
-     * the String returned to the caller.
+     * Gets a copy of the contents of this writer as a string.
      * 
-     * @return this StringWriters current contents as a String.
+     * @return this writer's contents as a string.
      */
     @Override
     public String toString() {
@@ -100,18 +100,18 @@
     }
 
     /**
-     * Writes <code>count</code> characters starting at <code>offset</code>
-     * in <code>cbuf</code> to this StringWriter.
+     * Writes {@code count} characters starting at {@code offset} in {@code buf}
+     * to this writer's {@code StringBuffer}.
      * 
      * @param cbuf
-     *            the non-null array containing characters to write.
+     *            the non-null character array to write.
      * @param offset
-     *            offset in buf to retrieve characters
+     *            the index of the first character in {@code cbuf} to write.
      * @param count
-     *            maximum number of characters to write
-     * 
-     * @throws ArrayIndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *            the maximum number of characters to write.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the size of {@code buf}.
      */
     @Override
     public void write(char[] cbuf, int offset, int count) {
@@ -127,12 +127,11 @@
     }
 
     /**
-     * Writes the specified character <code>oneChar</code> to this
-     * StringWriter. This implementation writes the low order two bytes to the
-     * Stream.
+     * Writes one character to this writer's {@code StringBuffer}. Only the two
+     * least significant bytes of the integer {@code oneChar} are written.
      * 
      * @param oneChar
-     *            The character to write
+     *            the character to write to this writer's {@code StringBuffer}.
      */
     @Override
     public void write(int oneChar) {
@@ -140,11 +139,11 @@
     }
 
     /**
-     * Writes the characters from the String <code>str</code> to this
-     * StringWriter.
+     * Writes the characters from the specified string to this writer's {@code
+     * StringBuffer}.
      * 
      * @param str
-     *            the non-null String containing the characters to write.
+     *            the non-null string containing the characters to write.
      */
     @Override
     public void write(String str) {
@@ -152,19 +151,18 @@
     }
 
     /**
-     * Writes <code>count</code> number of characters starting at
-     * <code>offset</code> from the String <code>str</code> to this
-     * StringWriter.
+     * Writes {@code count} characters from {@code str} starting at {@code
+     * offset} to this writer's {@code StringBuffer}.
      * 
      * @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 count
-     *            the number of characters to retrieve and write.
-     * 
-     * @throws ArrayIndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *            the number of characters from {@code str} to write.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the length of {@code str}.
      */
     @Override
     public void write(String str, int offset, int count) {
@@ -173,13 +171,12 @@
     }
 
     /**
-     * Append a char <code>c</code>to the StringWriter. The
-     * StringWriter.append(<code>c</code>) works the same way as
-     * StringWriter.write(<code>c</code>).
+     * Appends the character {@code c} to this writer's {@code StringBuffer}.
+     * This method works the same way as {@link #write(int)}.
      * 
      * @param c
-     *            The character appended to the StringWriter.
-     * @return The StringWriter.
+     *            the character to append to the target stream.
+     * @return this writer.
      */
     @Override
     public StringWriter append(char c) {
@@ -188,14 +185,14 @@
     }
 
     /**
-     * Append a CharSequence <code>csq</code> to the StringWriter. The
-     * StringWriter.append(<code>csq</code>) works the same way as
-     * StringWriter.write(<code>csq</code>.toString()). If <code>csq</code>
-     * is null, then "null" will be substituted for <code>csq</code>.
+     * Appends the character sequence {@code csq} to this writer's {@code
+     * StringBuffer}. This method works the same way as {@code
+     * StringWriter.write(csq.toString())}. If {@code csq} is {@code null}, then
+     * the string "null" is written to the target stream.
      * 
      * @param csq
-     *            The CharSequence appended to the StringWriter.
-     * @return The StringWriter
+     *            the character sequence appended to the target.
+     * @return this writer.
      */
     @Override
     public StringWriter append(CharSequence csq) {
@@ -208,26 +205,25 @@
     }
 
     /**
-     * Append a subsequence of a CharSequence <code>csq</code> to the
-     * StringWriter. The first char and the last char of the subsequnce is
-     * specified by the parameter <code>start</code> and <code>end</code>.
-     * The StringWriter.append(<code>csq</code>) works the same way as
-     * StringWriter.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>. s
+     * Appends a subsequence of the character sequence {@code csq} to this
+     * writer's {@code StringBuffer}. This method works the same way as {@code
+     * StringWriter.writer(csq.subsequence(start, end).toString())}. If {@code
+     * csq} is {@code null}, then the specified subsequence of the string "null"
+     * will be written to the target.
      * 
      * @param csq
-     *            The CharSequence appended to the StringWriter.
+     *            the character sequence appended to the target.
      * @param start
-     *            The index of the first char in the CharSequence appended to
-     *            the StringWriter.
+     *            the index of the first char in the character sequence appended
+     *            to the target.
      * @param end
-     *            The index of the char after the last one in the CharSequence
-     *            appended to the StringWriter.
-     * @return The StringWriter.
+     *            the index of the character following the last character of the
+     *            subsequence appended to the target.
+     * @return this writer.
      * @throws IndexOutOfBoundsException
-     *             If start is less than end, end is greater than the length of
-     *             the CharSequence, or start or end is negative.
+     *             if {@code start > end}, {@code start < 0}, {@code end < 0} or
+     *             either {@code start} or {@code end} are greater or equal than
+     *             the length of {@code csq}.
      */
     @Override
     public StringWriter append(CharSequence csq, int start, int end) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/SyncFailedException.java
Fri May  1 08:08:59 2009
@@ -18,21 +18,19 @@
 package java.io;
 
 /**
- * This IO exception is thrown when the method <code>sync()</code> in
- * FileDescriptor failed to complete.
- * 
- * @see FileDescriptor#sync()
+ * Signals that the {@link FileDescriptor#sync()} method has failed to
+ * complete.
  */
 public class SyncFailedException extends IOException {
 
     private static final long serialVersionUID = -2353342684412443330L;
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code SyncFailedException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            the detail message for the exception.
+     *            the detail message for this exception.
      */
     public SyncFailedException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UTFDataFormatException.java
Fri May  1 08:08:59 2009
@@ -18,8 +18,8 @@
 package java.io;
 
 /**
- * This IO exception is thrown when a program attempts to read a UTF-8 String
- * and the encoding is incorrect.
+ * Signals that an incorrectly encoded UTF-8 string has been encountered, most
+ * likely while reading some {@link DataInputStream}.
  * 
  * @see DataInputStream#readUTF()
  */
@@ -28,18 +28,19 @@
     private static final long serialVersionUID = 420743449228280612L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code UTFDataFormatException} with its stack trace
+     * filled in.
      */
     public UTFDataFormatException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code UTFDataFormatException} with its stack trace and
+     * detail message filled in.
      * 
      * @param detailMessage
-     *            the detail message for the exception.
+     *            the detail message for this exception.
      */
     public UTFDataFormatException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/UnsupportedEncodingException.java
Fri May  1 08:08:59 2009
@@ -18,26 +18,27 @@
 package java.io;
 
 /**
- * This IO exception is thrown when a program asks for a particular character
- * converter and it is not available.
+ * Thrown when a program asks for a particular character converter that is
+ * unavailable.
  */
 public class UnsupportedEncodingException extends IOException {
 
     private static final long serialVersionUID = -4274276298326136670L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code UnsupportedEncodingException} with its stack
+     * trace filled in.
      */
     public UnsupportedEncodingException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code UnsupportedEncodingException} with its stack
+     * trace and detail message filled in.
      * 
      * @param detailMessage
-     *            the detail message for the exception.
+     *            the detail message for this exception.
      */
     public UnsupportedEncodingException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/WriteAbortedException.java
Fri May  1 08:08:59 2009
@@ -18,9 +18,9 @@
 package java.io;
 
 /**
- * This type of exception is thrown by readObject() when it detects an exception
- * marker in the input stream. This marker indicates that when the object was
- * being serialized, an exception happened and this marker was inserted instead
+ * Signals that the {@link ObjectInputStream#readObject()} method has detected
+ * an exception marker in the input stream. This marker indicates that exception
+ * occurred when the object was serialized, and this marker was inserted instead
  * of the original object. It is a way to "propagate" an exception from the code
  * that attempted to write the object to the code that is attempting to read the
  * object.
@@ -32,20 +32,20 @@
     private static final long serialVersionUID = -3326426625597282442L;
 
     /**
-     * The exception that was caused when writeObject() was attempting to
-     * serialize the object
+     * The exception that occured when writeObject() was attempting to serialize
+     * the object.
      */
     public Exception detail;
 
     /**
-     * Constructs a new instance of this class with its walkback, message and
-     * the exception which caused the underlying problem when serializing the
-     * object filled in.
+     * Constructs a new {@code WriteAbortedException} with its stack trace,
+     * detail message and the exception which caused the underlying problem when
+     * serializing the object filled in.
      * 
      * @param detailMessage
-     *            the detail message for the exception.
+     *            the detail message for this exception.
      * @param rootCause
-     *            exception that caused the problem when serializing the object.
+     *            the exception that was thrown when serializing the object.
      */
     public WriteAbortedException(String detailMessage, Exception rootCause) {
         super(detailMessage);
@@ -54,11 +54,11 @@
     }
 
     /**
-     * Answers the extra information message which was provided when the
-     * throwable was created. If no message was provided at creation time, then
-     * answer null.
+     * Gets the extra information message which was provided when this exception
+     * was created. Returns {@code null} if no message was provided at creation
+     * time.
      * 
-     * @return the receiver's message.
+     * @return the exception message.
      */
     @Override
     public String getMessage() {
@@ -70,9 +70,9 @@
     }
 
     /**
-     * Answers the cause of this Throwable, or null if there is no cause.
+     * Gets the cause of this exception or {@code null} if there is no cause.
      * 
-     * @return the receiver's cause.
+     * @return the exception cause.
      */
     @Override
     public Throwable getCause() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java?rev=770573&r1=770572&r2=770573&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/io/Writer.java Fri May
 1 08:08:59 2009
@@ -18,9 +18,19 @@
 package java.io;
 
 /**
- * Writer is an Abstract class for writing Character Streams. Subclasses of
- * writer must implement the methods <code>write(char[], int, int)</code>,
- * <code>close()</code> and <code>flush()</code>.
+ * The base class for all writers. A writer is a means of writing data to a
+ * target in a character-wise manner. Most output streams expect the
+ * {@link #flush()} method to be called before closing the stream, to ensure all
+ * data is actually written out.
+ * <p>
+ * This abstract class does not provide a fully working implementation, so it
+ * needs to be subclassed, and at least the {@link #write(char[], int, int)},
+ * {@link #close()} and {@link #flush()} methods 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 readers for purposes like reading from a file already exist
+ * in this package.
  * 
  * @see Reader
  */
@@ -34,8 +44,8 @@
     protected Object lock;
 
     /**
-     * Constructs a new character stream Writer using <code>this</code> as the
-     * Object to synchronize critical regions around.
+     * Constructs a new {@code Writer} with {@code this} as the object used to
+     * synchronize critical sections.
      */
     protected Writer() {
         super();
@@ -43,11 +53,13 @@
     }
 
     /**
-     * Constructs a new character stream Writer using <code>lock</code> as the
-     * Object to synchronize critical regions around.
+     * Constructs a new {@code Writer} with {@code lock} used to synchronize
+     * critical sections.
      * 
      * @param lock
-     *            the Object to synchronize critical regions around.
+     *            the {@code Object} used to synchronize critical sections.
+     * @throws NullPointerException
+     *             if {@code lock} is {@code null}.
      */
     protected Writer(Object lock) {
         if (lock == null) {
@@ -57,63 +69,62 @@
     }
 
     /**
-     * Close this Writer. This must be implemented by any concrete subclasses.
-     * The implementation should free any resources associated with the Writer.
+     * Closes this writer. Implementations of this method should free any
+     * resources associated with the writer.
      * 
      * @throws IOException
-     *             If an error occurs attempting to close this Writer.
+     *             if an error occurs while closing this writer.
      */
     public abstract void close() throws IOException;
 
     /**
-     * Flush this Writer. This must be implemented by any concrete subclasses.
-     * The implementation should ensure all buffered characters are written out.
+     * Flushes this writer. Implementations of this method should ensure that
+     * all buffered characters are written to the target.
      * 
      * @throws IOException
-     *             If an error occurs attempting to flush this Writer.
+     *             if an error occurs while flushing this writer.
      */
     public abstract void flush() throws IOException;
 
     /**
-     * Writes the entire character buffer <code>buf</code> to this Writer.
+     * Writes the entire character buffer {@code buf} to the target.
      * 
      * @param buf
      *            the non-null array containing characters to write.
-     * 
      * @throws IOException
-     *             If this Writer has already been closed or some other
-     *             IOException occurs.
+     *             if this writer is closed or another I/O error occurs.
      */
     public void write(char buf[]) throws IOException {
         write(buf, 0, buf.length);
     }
 
     /**
-     * Writes <code>count</code> characters starting at <code>offset<code>
in
-     * <code>buf</code> to this Writer.  This abstract method must be implemented
-     * by concrete subclasses.
-     *
-     * @param 		buf			the non-null array containing characters to write.
-     * @param 		offset 		offset in buf to retrieve characters
-     * @param 		count 		maximum number of characters to write
+     * Writes {@code count} characters starting at {@code offset} in {@code buf}
+     * to the target.
      *
-     * @throws 		IOException 					If this Writer has already been closed or some other IOException
occurs.
-     * @throws		ArrayIndexOutOfBoundsException 	If offset or count are outside of bounds.
+     * @param buf
+     *            the non-null character array to write.
+     * @param offset
+     *            the index of the first character in {@code buf} to write.
+     * @param count
+     *            the maximum number of characters to write.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the size of {@code buf}.
+     * @throws IOException
+     *             if this writer is closed or another I/O error occurs.
      */
     public abstract void write(char buf[], int offset, int count)
             throws IOException;
 
     /**
-     * Writes the specified character <code>oneChar</code> to this Writer.
-     * This implementation writes the low order two bytes of
-     * <code>oneChar</code> to the Stream.
+     * Writes one character to the target. Only the two least significant bytes
+     * of the integer {@code oneChar} are written.
      * 
      * @param oneChar
-     *            The character to write
-     * 
+     *            the character to write to the target.
      * @throws IOException
-     *             If this Writer has already been closed or some other
-     *             IOException occurs.
+     *             if this writer is closed or another I/O error occurs.
      */
     public void write(int oneChar) throws IOException {
         synchronized (lock) {
@@ -124,14 +135,12 @@
     }
 
     /**
-     * Writes the characters from the String <code>str</code> to this Writer.
+     * Writes the characters from the specified string to the target.
      * 
      * @param str
-     *            the non-null String containing the characters to write.
-     * 
+     *            the non-null string containing the characters to write.
      * @throws IOException
-     *             If this Writer has already been closed or some other
-     *             IOException occurs.
+     *             if this writer is closed or another I/O error occurs.
      */
     public void write(String str) throws IOException {
         char buf[] = new char[str.length()];
@@ -142,21 +151,20 @@
     }
 
     /**
-     * Writes <code>count</code> number of characters starting at
-     * <code>offset</code> from the String <code>str</code> to this
Writer.
+     * Writes {@code count} characters from {@code str} starting at {@code
+     * offset} to the target.
      * 
      * @param str
-     *            the non-null String containing the characters to write.
+     *            the non-null string containing the characters to write.
      * @param offset
-     *            the starting point to retrieve characters.
+     *            the index of the first character in {@code str} to write.
      * @param count
-     *            the number of characters to retrieve and write.
-     * 
+     *            the number of characters from {@code str} to write.
      * @throws IOException
-     *             If this Writer has already been closed or some other
-     *             IOException occurs.
-     * @throws ArrayIndexOutOfBoundsException
-     *             If offset or count are outside of bounds.
+     *             if this writer is closed or another I/O error occurs.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset < 0} or {@code count < 0}, or if {@code
+     *             offset + count} is greater than the length of {@code str}.
      */
     public void write(String str, int offset, int count) throws IOException {
         if (count < 0) { // other cases tested by getChars()
@@ -171,14 +179,14 @@
     }
 
     /**
-     * Append a char <code>c</code>to the Writer. The Writer.append(<code>c</code>)
-     * works the same as Writer.write(<code>c</code>).
+     * Appends the character {@code c} to the target. This method works the same
+     * way as {@link #write(int)}.
      * 
      * @param c
-     *            The character appended to the Writer.
-     * @return The Writer.
+     *            the character to append to the target stream.
+     * @return this writer.
      * @throws IOException
-     *             If any IOException raises during the procedure.
+     *             if this writer is closed or another I/O error occurs.
      */
     public Writer append(char c) throws IOException {
         write(c);
@@ -186,16 +194,16 @@
     }
 
     /**
-     * Append a CharSequence <code>csq</code> to the Writer. The
-     * Writer.append(<code>csq</code>) works the same way as Writer.write(<code>csq</code>.toString()).
-     * If <code>csq</code> is null, then "null" will be substituted for
-     * <code>csq</code>.
+     * Appends the character sequence {@code csq} to the target. This method
+     * works the same way as {@code Writer.write(csq.toString())}. If {@code
+     * csq} is {@code null}, then the string "null" is written to the target
+     * stream.
      * 
      * @param csq
-     *            The CharSequence appended to the Writer.
-     * @return The Writer.
+     *            the character sequence appended to the target.
+     * @return this writer.
      * @throws IOException
-     *             If any IOException raises during the procedure.
+     *             if this writer is closed or another I/O error occurs.
      */
     public Writer append(CharSequence csq) throws IOException {
         if (null == csq) {
@@ -207,27 +215,27 @@
     }
 
     /**
-     * Append a subsequence of a CharSequence <code>csq</code> to the Writer.
-     * The first char and the last char of the subsequnce is specified by the
-     * parameter <code>start</code> and <code>end</code>. The
-     * Writer.append(<code>csq</code>) works the same way as Writer.write (<code>csq</code>csq.subSequence(<code>start</code>,<code>end</code>).toString).
-     * If <code>csq</code> is null, then "null" will be substituted for
-     * <code>csq</code>.
+     * Appends a subsequence of the character sequence {@code csq} to the
+     * target. This method works the same way as {@code
+     * Writer.writer(csq.subsequence(start, end).toString())}. If {@code
+     * csq} is {@code null}, then the specified subsequence of the string "null"
+     * will be written to the target.
      * 
      * @param csq
-     *            The CharSequence appended to the Writaer.
+     *            the character sequence appended to the target.
      * @param start
-     *            The index of the first char in the CharSequence appended to
-     *            the Writer.
+     *            the index of the first char in the character sequence appended
+     *            to the target.
      * @param end
-     *            The index of the char after the last one in the CharSequence
-     *            appended to the Writer.
-     * @return The Writer.
-     * @throws IndexOutOfBoundsException
-     *             If start is less than end, end is greater than the length of
-     *             the CharSequence, or start or end is negative.
+     *            the index of the character following the last character of the
+     *            subsequence appended to the target.
+     * @return this writer.
      * @throws IOException
-     *             If any IOException raises during the procedure.
+     *             if this writer is closed or another I/O error occurs.
+     * @throws IndexOutOfBoundsException
+     *             if {@code start > end}, {@code start < 0}, {@code end < 0} or
+     *             either {@code start} or {@code end} are greater or equal than
+     *             the length of {@code csq}.
      */
     public Writer append(CharSequence csq, int start, int end)
             throws IOException {



Mime
View raw message