harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770909 [9/10] - in /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang: ./ ref/ reflect/
Date Sat, 02 May 2009 08:09:57 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuffer.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuffer.java Sat May  2 08:09:50 2009
@@ -52,7 +52,7 @@
             new ObjectStreamField("value", char[].class), }; //$NON-NLS-1$
 
     /**
-     * Constructs a new StringBuffer using the default capacity.
+     * Constructs a new StringBuffer using the default capacity which is 16.
      */
     public StringBuffer() {
         super();
@@ -62,7 +62,7 @@
      * Constructs a new StringBuffer using the specified capacity.
      * 
      * @param capacity
-     *            the initial capacity
+     *            the initial capacity.
      */
     public StringBuffer(int capacity) {
         super(capacity);
@@ -70,29 +70,27 @@
 
     /**
      * Constructs a new StringBuffer containing the characters in the specified
-     * string and the default capacity.
+     * string. The capacity of the new buffer will be the length of the
+     * {@code String} plus the default capacity.
      * 
      * @param string
-     *            the string content with which to initialize the new
-     *            <code>StringBuffer</code> instance
+     *            the string content with which to initialize the new instance.
      * @throws NullPointerException
-     *             on supplying a <code>null</code> value of
-     *             <code>string</code>
+     *            if {@code string} is {@code null}.
      */
     public StringBuffer(String string) {
         super(string);
     }
 
     /**
-     * <p>
-     * Constructs a StringBuffer and initializes it with the characters in the
-     * <code>CharSequence</code>.
-     * </p>
+     * Constructs a StringBuffer and initializes it with the content from the
+     * specified {@code CharSequence}. The capacity of the new buffer will be
+     * the length of the {@code CharSequence} plus the default capacity.
      * 
      * @param cs
-     *            The <code>CharSequence</code> to initialize the instance.
+     *            the content to initialize the instance.
      * @throws NullPointerException
-     *             if the <code>cs</code> parameter is <code>null</code>.
+     *            if {@code cs} is {@code null}.
      * @since 1.5
      */
     public StringBuffer(CharSequence cs) {
@@ -102,21 +100,26 @@
     /**
      * Adds the string representation of the specified boolean to the end of
      * this StringBuffer.
-     * 
+     * <p>
+     * If the argument is {@code true} the string {@code "true"} is appended,
+     * otherwise the string {@code "false"} is appended.
+     *
      * @param b
-     *            the boolean
-     * @return this StringBuffer
+     *            the boolean to append.
+     * @return this StringBuffer.
+     * @see String#valueOf(boolean)
      */
     public StringBuffer append(boolean b) {
         return append(b ? "true" : "false"); //$NON-NLS-1$//$NON-NLS-2$
     }
 
     /**
-     * Adds the specified character to the end of this StringBuffer.
+     * Adds the specified character to the end of this buffer.
      * 
      * @param ch
-     *            a character
-     * @return this StringBuffer
+     *            the character to append.
+     * @return this StringBuffer.
+     * @see String#valueOf(char)
      */
     public synchronized StringBuffer append(char ch) {
         append0(ch);
@@ -128,8 +131,9 @@
      * StringBuffer.
      * 
      * @param d
-     *            the double
-     * @return this StringBuffer
+     *            the double to append.
+     * @return this StringBuffer.
+     * @see String#valueOf(double)
      */
     public StringBuffer append(double d) {
         return append(Double.toString(d));
@@ -140,8 +144,9 @@
      * StringBuffer.
      * 
      * @param f
-     *            the float
-     * @return this StringBuffer
+     *            the float to append.
+     * @return this StringBuffer.
+     * @see String#valueOf(float)
      */
     public StringBuffer append(float f) {
         return append(Float.toString(f));
@@ -151,12 +156,13 @@
      * Adds the string representation of the specified integer to the end of
      * this StringBuffer.
      * 
-     * @param value
-     *            the integer
-     * @return this StringBuffer
+     * @param i
+     *            the integer to append.
+     * @return this StringBuffer.
+     * @see String#valueOf(int)
      */
-    public StringBuffer append(int value) {
-        return append(Integer.toString(value));
+    public StringBuffer append(int i) {
+        return append(Integer.toString(i));
     }
 
     /**
@@ -164,8 +170,9 @@
      * StringBuffer.
      * 
      * @param l
-     *            the long
-     * @return this StringBuffer
+     *            the long to append.
+     * @return this StringBuffer.
+     * @see String#valueOf(long)
      */
     public StringBuffer append(long l) {
         return append(Long.toString(l));
@@ -174,10 +181,15 @@
     /**
      * Adds the string representation of the specified object to the end of this
      * StringBuffer.
-     * 
+     * <p>
+     * If the specified object is {@code null} the string {@code "null"} is
+     * appended, otherwise the objects {@code toString} is used to get its
+     * string representation.
+     *
      * @param obj
-     *            the object
-     * @return this StringBuffer
+     *            the object to append (may be null).
+     * @return this StringBuffer.
+     * @see String#valueOf(Object)
      */
     public synchronized StringBuffer append(Object obj) {
         if (obj == null) {
@@ -189,11 +201,14 @@
     }
 
     /**
-     * Adds the specified string to the end of this StringBuffer.
-     * 
+     * Adds the specified string to the end of this buffer.
+     * <p>
+     * If the specified string is {@code null} the string {@code "null"} is
+     * appended, otherwise the contents of the specified string is appended.
+     *
      * @param string
-     *            the string
-     * @return this StringBuffer
+     *            the string to append (may be null).
+     * @return this StringBuffer.
      */
     public synchronized StringBuffer append(String string) {
         append0(string);
@@ -201,11 +216,15 @@
     }
 
     /**
-     * Adds the specified StringBuffer to the end of this StringBuffer.
-     * 
+     * Adds the specified StringBuffer to the end of this buffer.
+     * <p>
+     * If the specified StringBuffer is {@code null} the string {@code "null"}
+     * is appended, otherwise the contents of the specified StringBuffer is
+     * appended.
+     *
      * @param sb
-     *            the StringBuffer
-     * @return this StringBuffer
+     *            the StringBuffer to append (may be null).
+     * @return this StringBuffer.
      * 
      * @since 1.4
      */
@@ -221,14 +240,13 @@
     }
 
     /**
-     * Adds the character array to the end of this StringBuffer.
+     * Adds the character array to the end of this buffer.
      * 
      * @param chars
-     *            the character array
-     * @return this StringBuffer
-     * 
+     *            the character array to append.
+     * @return this StringBuffer.
      * @throws NullPointerException
-     *             when chars is null
+     *            if {@code chars} is {@code null}.
      */
     public synchronized StringBuffer append(char chars[]) {
         append0(chars);
@@ -236,22 +254,20 @@
     }
 
     /**
-     * Adds the specified sequence of characters to the end of this
-     * StringBuffer.
+     * Adds the specified sequence of characters to the end of this buffer.
      * 
      * @param chars
-     *            a character array
+     *            the character array to append.
      * @param start
-     *            the starting offset
+     *            the starting offset.
      * @param length
-     *            the number of characters
-     * @return this StringBuffer
-     * 
+     *            the number of characters.
+     * @return this StringBuffer.
      * @throws ArrayIndexOutOfBoundsException
-     *             when <code>length < 0, start < 0</code> or
-     *             <code>start + length > chars.length</code>
+     *             if {@code length < 0} , {@code start < 0} or {@code start +
+     *             length > chars.length}.
      * @throws NullPointerException
-     *             when chars is null
+     *            if {@code chars} is {@code null}.
      */
     public synchronized StringBuffer append(char chars[], int start, int length) {
         append0(chars, start, length);
@@ -259,15 +275,15 @@
     }
 
     /**
+     * Appends the specified CharSequence to this buffer.
      * <p>
-     * Appends the <code>CharSequence</code> to this buffer. If the
-     * <code>CharSequence</code> is <code>null</code>, then the string
-     * <code>"null"</code> is appended.
-     * </p>
-     * 
+     * If the specified CharSequence is {@code null} the string {@code "null"}
+     * is appended, otherwise the contents of the specified CharSequence is
+     * appended.
+     *
      * @param s
-     *            The <code>CharSequence</code> to append.
-     * @return A reference to this object.
+     *            the CharSequence to append.
+     * @return this StringBuffer.
      * @since 1.5
      */
     public synchronized StringBuffer append(CharSequence s) {
@@ -280,27 +296,23 @@
     }
 
     /**
+     * Appends the specified subsequence of the CharSequence to this buffer.
      * <p>
-     * Appends the subsequence of the <code>CharSequence</code> to this
-     * buffer. If the <code>CharSequence</code> is <code>null</code>, then
-     * the string <code>"null"</code> is used to extract a subsequence.
-     * </p>
-     * 
+     * If the specified CharSequence is {@code null}, then the string {@code
+     * "null"} is used to extract a subsequence.
+     *
      * @param s
-     *            The <code>CharSequence</code> to append.
+     *            the CharSequence to append.
      * @param start
-     *            The inclusive start index of the subsequence of the
-     *            <code>CharSequence</code>.
+     *            the inclusive start index.
      * @param end
-     *            The exclusive end index of the subsequence of the
-     *            <code>CharSequence</code>.
-     * @return A reference to this object.
-     * @since 1.5
+     *            the exclusive end index.
+     * @return this StringBuffer.
      * @throws IndexOutOfBoundsException
-     *             if <code>start</code> or <code>end</code> are negative,
-     *             <code>start</code> is greater than <code>end</code> or
-     *             <code>end</code> is greater than the length of
-     *             <code>s</code>.
+     *             if {@code start} or {@code end} are negative, {@code start}
+     *             is greater than {@code end} or {@code end} is greater than
+     *             the length of {@code s}.
+     * @since 1.5
      */
     public synchronized StringBuffer append(CharSequence s, int start, int end) {
         append0(s, start, end);
@@ -308,15 +320,15 @@
     }
 
     /**
+     * Appends the string representation of the specified Unicode code point to
+     * the end of this buffer.
      * <p>
-     * Appends the encoded Unicode code point to this object. The code point is
-     * converted to a <code>char[]</code> as defined by
+     * The code point is converted to a {@code char[]} as defined by
      * {@link Character#toChars(int)}.
-     * </p>
-     * 
+     *
      * @param codePoint
-     *            The Unicode code point to encode and append.
-     * @return A reference to this object.
+     *            the Unicode code point to encode and append.
+     * @return this StringBuffer.
      * @see Character#toChars(int)
      * @since 1.5
      */
@@ -324,82 +336,21 @@
         return append(Character.toChars(codePoint));
     }
 
-    /**
-     * Answers the character at the specified offset in this StringBuffer.
-     * 
-     * @param index
-     *            the zero-based index in this StringBuffer
-     * @return the character at the index
-     * 
-     * @throws IndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index >= length()</code>
-     */
     @Override
     public synchronized char charAt(int index) {
         return super.charAt(index);
     }
 
-    /**
-     * <p>
-     * Retrieves the Unicode code point value at the <code>index</code>.
-     * </p>
-     * 
-     * @param index
-     *            The index to the <code>char</code> code unit within this
-     *            object.
-     * @return The Unicode code point value.
-     * @throws IndexOutOfBoundsException
-     *             if <code>index</code> is negative or greater than or equal
-     *             to {@link #length()}.
-     * @see Character
-     * @see Character#codePointAt(char[], int, int)
-     * @since 1.5
-     */
     @Override
     public synchronized int codePointAt(int index) {
         return super.codePointAt(index);
     }
 
-    /**
-     * <p>
-     * Retrieves the Unicode code point value that precedes the
-     * <code>index</code>.
-     * </p>
-     * 
-     * @param index
-     *            The index to the <code>char</code> code unit within this
-     *            object.
-     * @return The Unicode code point value.
-     * @throws IndexOutOfBoundsException
-     *             if <code>index</code> is less than 1 or greater than
-     *             {@link #length()}.
-     * @see Character
-     * @see Character#codePointBefore(char[], int, int)
-     * @since 1.5
-     */
     @Override
     public synchronized int codePointBefore(int index) {
         return super.codePointBefore(index);
     }
 
-    /**
-     * <p>
-     * Calculates the number of Unicode code points between
-     * <code>beginIndex</code> and <code>endIndex</code>.
-     * </p>
-     * 
-     * @param beginIndex
-     *            The inclusive beginning index of the subsequence.
-     * @param endIndex
-     *            The exclusive end index of the subsequence.
-     * @return The number of Unicode code points in the subsequence.
-     * @throws IndexOutOfBoundsException
-     *             if <code>beginIndex</code> is negative or greater than
-     *             <code>endIndex</code> or <code>endIndex</code> is greater
-     *             than {@link #length()}.
-     * @since 1.5
-     */
     @Override
     public synchronized int codePointCount(int beginIndex, int endIndex) {
         return super.codePointCount(beginIndex, endIndex);
@@ -409,14 +360,13 @@
      * Deletes a range of characters.
      * 
      * @param start
-     *            the offset of the first character
+     *            the offset of the first character.
      * @param end
-     *            the offset one past the last character
-     * @return this StringBuffer
-     * 
+     *            the offset one past the last character.
+     * @return this StringBuffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>start < 0, start > end</code> or
-     *             <code>end > length()</code>
+     *             if {@code start < 0}, {@code start > end} or {@code end >
+     *             length()}.
      */
     public synchronized StringBuffer delete(int start, int end) {
         delete0(start, end);
@@ -424,91 +374,61 @@
     }
 
     /**
-     * Deletes a single character
+     * Deletes the character at the specified offset.
      * 
      * @param location
-     *            the offset of the character to delete
-     * @return this StringBuffer
-     * 
+     *            the offset of the character to delete.
+     * @return this StringBuffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>location < 0</code> or
-     *             <code>location >= length()</code>
+     *             if {@code location < 0} or {@code location >= length()}
      */
     public synchronized StringBuffer deleteCharAt(int location) {
         deleteCharAt0(location);
         return this;
     }
 
-    /**
-     * Ensures that this StringBuffer can hold the specified number of
-     * characters without growing.
-     * 
-     * @param min
-     *            the minimum number of elements that this StringBuffer will
-     *            hold before growing
-     */
     @Override
     public synchronized void ensureCapacity(int min) {
         super.ensureCapacity(min);
     }
 
     /**
-     * Copies the specified characters in this StringBuffer to the character
-     * array starting at the specified offset in the character array.
+     * Copies the requested sequence of characters to the {@code char[]} passed
+     * starting at {@code idx}.
      * 
      * @param start
-     *            the starting offset of characters to copy
+     *            the starting offset of characters to copy.
      * @param end
-     *            the ending offset of characters to copy
+     *            the ending offset of characters to copy.
      * @param buffer
-     *            the destination character array
-     * @param index
-     *            the starting offset in the character array
-     * 
+     *            the destination character array.
+     * @param idx
+     *            the starting offset in the character array.
      * @throws IndexOutOfBoundsException
-     *             when <code>start < 0, end > length(),
-     *				start > end, index < 0, end - start > buffer.length - index</code>
-     * @throws NullPointerException
-     *             when buffer is null
+     *             if {@code start < 0}, {@code end > length()}, {@code start >
+     *             end}, {@code index < 0}, {@code end - start > buffer.length -
+     *             index}
      */
     @Override
-    public synchronized void getChars(int start, int end, char[] buffer, int index) {
-        super.getChars(start, end, buffer, index);
+    public synchronized void getChars(int start, int end, char[] buffer, int idx) {
+        super.getChars(start, end, buffer, idx);
     }
 
-    /**
-     * Searches in this StringBuffer for the index of the specified character.
-     * The search for the character starts at the specified offset and moves
-     * towards the end.
-     * 
-     * @param subString
-     *            the string to find
-     * @param start
-     *            the starting offset
-     * @return the index in this StringBuffer of the specified character, -1 if
-     *         the character isn't found
-     * 
-     * @see #lastIndexOf(String,int)
-     * 
-     * @since 1.4
-     */
     @Override
     public synchronized int indexOf(String subString, int start) {
         return super.indexOf(subString, start);
     }
 
     /**
-     * Inserts the character at the specified offset in this StringBuffer.
+     * Inserts the character into this buffer at the specified offset.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param ch
-     *            the character to insert
-     * @return this StringBuffer
-     * 
+     *            the character to insert.
+     * @return this buffer.
      * @throws ArrayIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public synchronized StringBuffer insert(int index, char ch) {
         insert0(index, ch);
@@ -516,125 +436,118 @@
     }
 
     /**
-     * Inserts the string representation of the specified boolean at the
-     * specified offset in this StringBuffer.
+     * Inserts the string representation of the specified boolean into this
+     * buffer at the specified offset.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param b
-     *            the boolean to insert
-     * @return this StringBuffer
-     * 
+     *            the boolean to insert.
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public StringBuffer insert(int index, boolean b) {
         return insert(index, b ? "true" : "false"); //$NON-NLS-1$ //$NON-NLS-2$
     }
 
     /**
-     * Inserts the string representation of the specified integer at the
-     * specified offset in this StringBuffer.
+     * Inserts the string representation of the specified integer into this
+     * buffer at the specified offset.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param i
-     *            the integer to insert
-     * @return this StringBuffer
-     * 
+     *            the integer to insert.
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public StringBuffer insert(int index, int i) {
         return insert(index, Integer.toString(i));
     }
 
     /**
-     * Inserts the string representation of the specified long at the specified
-     * offset in this StringBuffer.
+     * Inserts the string representation of the specified long into this buffer
+     * at the specified offset.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param l
-     *            the long to insert
-     * @return this StringBuffer
-     * 
+     *            the long to insert.
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public StringBuffer insert(int index, long l) {
         return insert(index, Long.toString(l));
     }
 
     /**
-     * Inserts the string representation of the specified double at the
-     * specified offset in this StringBuffer.
+     * Inserts the string representation of the specified into this buffer
+     * double at the specified offset.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param d
-     *            the double to insert
-     * @return this StringBuffer
-     * 
+     *            the double to insert.
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public StringBuffer insert(int index, double d) {
         return insert(index, Double.toString(d));
     }
 
     /**
-     * Inserts the string representation of the specified float at the specified
-     * offset in this StringBuffer.
+     * Inserts the string representation of the specified float into this buffer
+     * at the specified offset.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param f
-     *            the float to insert
-     * @return this StringBuffer
-     * 
+     *            the float to insert.
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public StringBuffer insert(int index, float f) {
         return insert(index, Float.toString(f));
     }
 
     /**
-     * Inserts the string representation of the specified object at the
-     * specified offset in this StringBuffer.
-     * 
+     * Inserts the string representation of the specified object into this
+     * buffer at the specified offset.
+     * <p>
+     * If the specified object is {@code null}, the string {@code "null"} is
+     * inserted, otherwise the objects {@code toString} method is used to get
+     * its string representation.
+     *
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param obj
-     *            the object to insert
-     * @return this StringBuffer
-     * 
+     *            the object to insert (may be null).
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public StringBuffer insert(int index, Object obj) {
         return insert(index, obj == null ? "null" : obj.toString()); //$NON-NLS-1$
     }
 
     /**
-     * Inserts the string at the specified offset in this StringBuffer.
-     * 
+     * Inserts the string into this buffer at the specified offset.
+     * <p>
+     * If the specified string is {@code null}, the string {@code "null"} is
+     * inserted, otherwise the contents of the string is inserted.
+     *
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param string
-     *            the string to insert
-     * @return this StringBuffer
-     * 
+     *            the string to insert (may be null).
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      */
     public synchronized StringBuffer insert(int index, String string) {
         insert0(index, string);
@@ -642,19 +555,17 @@
     }
 
     /**
-     * Inserts the character array at the specified offset in this StringBuffer.
+     * Inserts the character array into this buffer at the specified offset.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param chars
-     *            the character array to insert
-     * @return this StringBuffer
-     * 
+     *            the character array to insert.
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index > length()</code>
+     *             if {@code index < 0} or {@code index > length()}.
      * @throws NullPointerException
-     *             when chars is null
+     *            if {@code chars} is {@code null}.
      */
     public synchronized StringBuffer insert(int index, char[] chars) {
         insert0(index, chars);
@@ -662,25 +573,24 @@
     }
 
     /**
-     * Inserts the specified sequence of characters at the specified offset in
-     * this StringBuffer.
+     * Inserts the specified subsequence of characters into this buffer at the
+     * specified index.
      * 
      * @param index
-     *            the index at which to insert
+     *            the index at which to insert.
      * @param chars
-     *            a character array
+     *            the character array to insert.
      * @param start
-     *            the starting offset
+     *            the starting offset.
      * @param length
-     *            the number of characters
-     * @return this StringBuffer
-     * 
-     * @throws StringIndexOutOfBoundsException
-     *             when <code>length < 0, start < 0,</code>
-     *				<code>start + length > chars.length, index < 0</code>
-     *             or <code>index > length()</code>
+     *            the number of characters.
+     * @return this buffer.
      * @throws NullPointerException
-     *             when chars is null
+     *             if {@code chars} is {@code null}.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code length < 0}, {@code start < 0}, {@code start +
+     *             length > chars.length}, {@code index < 0} or {@code index >
+     *             length()}
      */
     public synchronized StringBuffer insert(int index, char chars[], int start,
             int length) {
@@ -689,20 +599,20 @@
     }
 
     /**
+     * Inserts the specified CharSequence into this buffer at the specified
+     * index.
      * <p>
-     * Inserts the <code>CharSequence</code> into this buffer at the
-     * <code>index</code>. If <code>CharSequence</code> is
-     * <code>null</code>, then the string <code>"null"</code> is inserted.
-     * </p>
-     * 
+     * If the specified CharSequence is {@code null}, the string {@code "null"}
+     * is inserted, otherwise the contents of the CharSequence.
+     *
      * @param index
-     *            The index of this buffer to insert the sequence.
+     *            The index at which to insert.
      * @param s
-     *            The <code>CharSequence</code> to insert.
-     * @return A reference to this object.
-     * @since 1.5
+     *            The char sequence to insert.
+     * @return this buffer.
      * @throws IndexOutOfBoundsException
-     *             if the index is invalid.
+     *             if {@code index < 0} or {@code index > length()}.
+     * @since 1.5
      */
     public synchronized StringBuffer insert(int index, CharSequence s) {
         insert0(index, s == null ? "null" : s.toString()); //$NON-NLS-1$
@@ -710,30 +620,27 @@
     }
 
     /**
+     * Inserts the specified subsequence into this buffer at the specified
+     * index.
      * <p>
-     * Inserts the <code>CharSequence</code> into this buffer at the
-     * <code>index</code>. If <code>CharSequence</code> is
-     * <code>null</code>, then the string <code>"null"</code> is inserted.
-     * </p>
+     * If the specified CharSequence is {@code null}, the string {@code "null"}
+     * is inserted, otherwise the contents of the CharSequence.
      * 
      * @param index
-     *            The index of this buffer to insert the sequence.
+     *            The index at which to insert.
      * @param s
-     *            The <code>CharSequence</code> to insert.
+     *            The char sequence to insert.
      * @param start
-     *            The inclusive start index of the subsequence of the
-     *            <code>CharSequence</code>.
+     *            The inclusive start index in the char sequence.
      * @param end
-     *            The exclusive end index of the subsequence of the
-     *            <code>CharSequence</code>.
-     * @return A reference to this object.
-     * @since 1.5
+     *            The exclusive end index in the char sequence.
+     * @return this buffer.
      * @throws IndexOutOfBoundsException
-     *             if <code>index</code> is negative or greater than the
-     *             current length, <code>start</code> or <code>end</code>
-     *             are negative, <code>start</code> is greater than
-     *             <code>end</code> or <code>end</code> is greater than the
-     *             length of <code>s</code>.
+     *             if {@code index} is negative or greater than the current
+     *             length, {@code start} or {@code end} are negative, {@code
+     *             start} is greater than {@code end} or {@code end} is greater
+     *             than the length of {@code s}.
+     * @since 1.5
      */
     public synchronized StringBuffer insert(int index, CharSequence s,
             int start, int end) {
@@ -741,64 +648,31 @@
         return this;
     }
 
-    /**
-     * Searches in this StringBuffer for the index of the specified character.
-     * The search for the character starts at the specified offset and moves
-     * towards the beginning.
-     * 
-     * @param subString
-     *            the string to find
-     * @param start
-     *            the starting offset
-     * @return the index in this StringBuffer of the specified character, -1 if
-     *         the character isn't found
-     * 
-     * @see #indexOf(String,int)
-     * 
-     * @since 1.4
-     */
     @Override
     public synchronized int lastIndexOf(String subString, int start) {
         return super.lastIndexOf(subString, start);
     }
 
-    /**
-     * <p>
-     * Returns the index within this object that is offset from
-     * <code>index</code> by <code>codePointOffset</code> code points.
-     * </p>
-     * 
-     * @param index
-     *            The index within this object to calculate the offset from.
-     * @param codePointOffset
-     *            The number of code points to count.
-     * @return The index within this object that is the offset.
-     * @throws IndexOutOfBoundsException
-     *             if <code>index</code> is negative or greater than
-     *             {@link #length()} or if there aren't enough code points
-     *             before or after <code>index</code> to match
-     *             <code>codePointOffset</code>.
-     * @since 1.5
-     */
     @Override
     public synchronized int offsetByCodePoints(int index, int codePointOffset) {
         return super.offsetByCodePoints(index, codePointOffset);
     }
 
     /**
-     * Replace a range of characters with the characters in the specified
-     * String.
+     * Replaces the characters in the specified range with the contents of the
+     * specified string.
      * 
      * @param start
-     *            the offset of the first character
+     *            the inclusive begin index.
      * @param end
-     *            the offset one past the last character
+     *            the exclusive end index.
      * @param string
-     *            a String
-     * @return this StringBuffer
-     * 
+     *            the string that will replace the contents in the range.
+     * @return this buffer.
      * @throws StringIndexOutOfBoundsException
-     *             when <code>start < 0</code> or <code>start > end</code>
+     *             if {@code start} or {@code end} are negative, {@code start}
+     *             is greater than {@code end} or {@code end} is greater than
+     *             the length of {@code s}.
      */
     public synchronized StringBuffer replace(int start, int end, String string) {
         replace0(start, end, string);
@@ -806,125 +680,45 @@
     }
 
     /**
-     * Reverses the order of characters in this StringBuffer.
+     * Reverses the order of characters in this buffer.
      * 
-     * @return this StringBuffer
+     * @return this buffer.
      */
     public synchronized StringBuffer reverse() {
         reverse0();
         return this;
     }
 
-    /**
-     * Sets the character at the specified offset in this StringBuffer.
-     * 
-     * @param index
-     *            the zero-based index in this StringBuffer
-     * @param ch
-     *            the character
-     * 
-     * @throws IndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index >= length()</code>
-     */
     @Override
     public synchronized void setCharAt(int index, char ch) {
         super.setCharAt(index, ch);
     }
 
-    /**
-     * Sets the length of this StringBuffer to the specified length. If there
-     * are more than length characters in this StringBuffer, the characters at
-     * end are lost. If there are less than length characters in the
-     * StringBuffer, the additional characters are set to <code>&#92;u0000</code>.
-     * 
-     * @param length
-     *            the new length of this StringBuffer
-     * 
-     * @throws IndexOutOfBoundsException
-     *             when <code>length < 0</code>
-     * 
-     * @see #length()
-     */
     @Override
     public synchronized void setLength(int length) {
         super.setLength(length);
     }
 
-    /**
-     * Copies a range of characters into a new String.
-     * 
-     * @param start
-     *            the offset of the first character
-     * @param end
-     *            the offset one past the last character
-     * @return a new String containing the characters from start to end - 1
-     * 
-     * @throws IndexOutOfBoundsException
-     *             when <code>start < 0, start > end</code> or
-     *             <code>end > length()</code>
-     * 
-     * @since 1.4
-     */
     @Override
     public synchronized CharSequence subSequence(int start, int end) {
         return super.substring(start, end);
     }
 
-    /**
-     * Copies a range of characters into a new String.
-     * 
-     * @param start
-     *            the offset of the first character
-     * @return a new String containing the characters from start to the end of
-     *         the string
-     * 
-     * @throws StringIndexOutOfBoundsException
-     *             when <code>start < 0</code> or
-     *             <code>start > length()</code>
-     */
     @Override
     public synchronized String substring(int start) {
         return super.substring(start);
     }
 
-    /**
-     * Copies a range of characters into a new String.
-     * 
-     * @param start
-     *            the offset of the first character
-     * @param end
-     *            the offset one past the last character
-     * @return a new String containing the characters from start to end - 1
-     * 
-     * @throws StringIndexOutOfBoundsException
-     *             when <code>start < 0, start > end</code> or
-     *             <code>end > length()</code>
-     */
     @Override
     public synchronized String substring(int start, int end) {
         return super.substring(start, end);
     }
 
-    /**
-     * Answers the contents of this StringBuffer.
-     * 
-     * @return a String containing the characters in this StringBuffer
-     */
     @Override
     public synchronized String toString() {
         return super.toString();
     }
 
-    /**
-     * <p>
-     * Trims the storage capacity of this buffer down to the size of the current
-     * character sequence. Execution of this method may change the results
-     * returned by the {@link #capacity()} method, but this is not required.
-     * </p>
-     * 
-     * @since 1.5
-     */
     @Override
     public synchronized void trimToSize() {
         super.trimToSize();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuilder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuilder.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuilder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringBuilder.java Sat May  2 08:09:50 2009
@@ -23,24 +23,20 @@
 import java.io.Serializable;
 
 /**
- * <p>
  * A modifiable {@link CharSequence sequence of characters} for use in creating
  * and modifying Strings. This class is intended as a direct replacement of
- * {@link java.lang.StringBuffer} for non-concurrent use; unlike
- * <code>StringBuffer</code> this class is not synchronized for thread safety.
- * </p>
- * 
+ * {@link StringBuffer} for non-concurrent use; unlike {@code StringBuffer} this
+ * class is not synchronized for thread safety.
  * <p>
- * The majority of the modification methods on this class return
- * <code>StringBuilder</code>, so that, like <code>StringBuffer</code>s,
- * they can be used in chaining method calls together. For example,
- * <code>new StringBuilder("One should ").append("always strive ").append("to achieve Harmony")</code>.
- * </p>
+ * The majority of the modification methods on this class return {@code
+ * StringBuilder}, so that, like {@code StringBuffer}s, they can be used in
+ * chaining method calls together. For example, {@code new StringBuilder("One
+ * should ").append("always strive ").append("to achieve Harmony")}.
  * 
- * @see java.lang.CharSequence
- * @see java.lang.Appendable
- * @see java.lang.StringBuffer
- * @see java.lang.String
+ * @see CharSequence
+ * @see Appendable
+ * @see StringBuffer
+ * @see String
  * 
  * @since 1.5
  */
@@ -50,9 +46,7 @@
     private static final long serialVersionUID = 4383685877147921099L;
 
     /**
-     * <p>
-     * Constructs an instance with an initial capacity of <code>16</code>.
-     * </p>
+     * Constructs an instance with an initial capacity of {@code 16}.
      * 
      * @see #capacity()
      */
@@ -61,15 +55,12 @@
     }
 
     /**
-     * <p>
-     * Constructs an instance with a specified capacity.
-     * </p>
-     * 
-     * @param capacity The initial capacity to use.
-     * 
-     * @throws NegativeArraySizeException if the <code>capacity</code>
-     *         parameter is <code>null</code>.
-     * 
+     * Constructs an instance with the specified capacity.
+     *
+     * @param capacity
+     *            the initial capacity to use.
+     * @throws NegativeArraySizeException
+     *             if the specified {@code capacity} is negative.
      * @see #capacity()
      */
     public StringBuilder(int capacity) {
@@ -77,45 +68,41 @@
     }
 
     /**
-     * <p>
-     * Constructs an instance that's populated by a {@link CharSequence}. The
-     * capacity of the new builder will bee the length of the
-     * <code>CharSequence</code> plus 16.
-     * </p>
-     * 
-     * @param seq The <code>CharSequence</code> to copy into the builder.
-     * @throws NullPointerException if the <code>seq</code> parameter is
-     *         <code>null</code>.
+     * Constructs an instance that's initialized with the contents of the
+     * specified {@code CharSequence}. The capacity of the new builder will be
+     * the length of the {@code CharSequence} plus 16.
+     *
+     * @param seq
+     *            the {@code CharSequence} to copy into the builder.
+     * @throws NullPointerException
+     *            if {@code seq} is {@code null}.
      */
     public StringBuilder(CharSequence seq) {
         super(seq.toString());
     }
 
     /**
-     * <p>
-     * Constructs an instance that's populated by a {@link String}. The
-     * capacity of the new builder will bee the length of the
-     * <code>String</code> plus 16.
-     * </p>
-     * 
-     * @param str The <code>String</code> to copy into the builder.
-     * @throws NullPointerException if the <code>str</code> parameter is
-     *         <code>null</code>.
+     * Constructs an instance that's initialized with the contents of the
+     * specified {@code String}. The capacity of the new builder will be the
+     * length of the {@code String} plus 16.
+     *
+     * @param str
+     *            the {@code String} to copy into the builder.
+     * @throws NullPointerException
+     *            if {@code str} is {@code null}.
      */
     public StringBuilder(String str) {
         super(str);
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>boolean</code> value
-     * passed. The <code>boolean</code> value is converted to a String
-     * according to the rule defined by {@link String#valueOf(boolean)}.
-     * </p>
-     * 
-     * @param b The <code>boolean</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code boolean} value.
+     * The {@code boolean} value is converted to a String according to the rule
+     * defined by {@link String#valueOf(boolean)}.
+     *
+     * @param b
+     *            the {@code boolean} value to append.
+     * @return this builder.
      * @see String#valueOf(boolean)
      */
     public StringBuilder append(boolean b) {
@@ -124,15 +111,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>char</code> value
-     * passed. The <code>char</code> value is converted to a String according
-     * to the rule defined by {@link String#valueOf(char)}.
-     * </p>
-     * 
-     * @param c The <code>char</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code char} value.
+     * The {@code char} value is converted to a string according to the rule
+     * defined by {@link String#valueOf(char)}.
+     *
+     * @param c
+     *            the {@code char} value to append.
+     * @return this builder.
      * @see String#valueOf(char)
      */
     public StringBuilder append(char c) {
@@ -141,15 +126,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>int</code> value passed.
-     * The <code>int</code> value is converted to a String according to the
-     * rule defined by {@link String#valueOf(int)}.
-     * </p>
-     * 
-     * @param i The <code>int</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code int} value. The
+     * {@code int} value is converted to a string according to the rule defined
+     * by {@link String#valueOf(int)}.
+     *
+     * @param i
+     *            the {@code int} value to append.
+     * @return this builder.
      * @see String#valueOf(int)
      */
     public StringBuilder append(int i) {
@@ -158,15 +141,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>long</code> value
-     * passed. The <code>long</code> value is converted to a String according
-     * to the rule defined by {@link String#valueOf(long)}.
-     * </p>
-     * 
-     * @param lng The <code>long</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code long} value.
+     * The {@code long} value is converted to a string according to the rule
+     * defined by {@link String#valueOf(long)}.
+     *
+     * @param lng
+     *            the {@code long} value.
+     * @return this builder.
      * @see String#valueOf(long)
      */
     public StringBuilder append(long lng) {
@@ -175,15 +156,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>float</code> value
-     * passed. The <code>float</code> value is converted to a String according
-     * to the rule defined by {@link String#valueOf(float)}.
-     * </p>
-     * 
-     * @param f The <code>float</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code float} value.
+     * The {@code float} value is converted to a string according to the rule
+     * defined by {@link String#valueOf(float)}.
+     *
+     * @param f
+     *            the {@code float} value to append.
+     * @return this builder.
      * @see String#valueOf(float)
      */
     public StringBuilder append(float f) {
@@ -192,15 +171,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>double</code> value
-     * passed. The <code>double</code> value is converted to a String
-     * according to the rule defined by {@link String#valueOf(double)}.
-     * </p>
-     * 
-     * @param d The <code>double</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code double} value.
+     * The {@code double} value is converted to a string according to the rule
+     * defined by {@link String#valueOf(double)}.
+     *
+     * @param d
+     *            the {@code double} value to append.
+     * @return this builder.
      * @see String#valueOf(double)
      */
     public StringBuilder append(double d) {
@@ -209,15 +186,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>Object</code> value
-     * passed. The <code>Object</code> value is converted to a String
-     * according to the rule defined by {@link String#valueOf(Object)}.
-     * </p>
-     * 
-     * @param obj The <code>Object</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code Object}.
+     * The {@code Object} value is converted to a string according to the rule
+     * defined by {@link String#valueOf(Object)}.
+     *
+     * @param obj
+     *            the {@code Object} to append.
+     * @return this builder.
      * @see String#valueOf(Object)
      */
     public StringBuilder append(Object obj) {
@@ -230,13 +205,12 @@
     }
 
     /**
-     * <p>
-     * Appends the contents of the String. If the String passed is
-     * <code>null</code>, then the String <code>"null"</code> is appended.
-     * </p>
-     * 
-     * @param str The String to append to this object.
-     * @return A reference to this object.
+     * Appends the contents of the specified string. If the string is {@code
+     * null}, then the string {@code "null"} is appended.
+     *
+     * @param str
+     *            the string to append.
+     * @return this builder.
      */
     public StringBuilder append(String str) {
         append0(str);
@@ -244,14 +218,13 @@
     }
 
     /**
-     * <p>
-     * Appends the contents of the StringBuffer. If the StringBuffer passed is
-     * <code>null</code>, then the StringBuffer <code>"null"</code> is
+     * Appends the contents of the specified {@code StringBuffer}. If the
+     * StringBuffer is {@code null}, then the string {@code "null"} is
      * appended.
-     * </p>
-     * 
-     * @param sb The StringBuffer to append to this object.
-     * @return A reference to this object.
+     *
+     * @param sb
+     *            the {@code StringBuffer} to append.
+     * @return this builder.
      */
     public StringBuilder append(StringBuffer sb) {
         if (sb == null) {
@@ -263,15 +236,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>char[]</code> value
-     * passed. The <code>char[]</code> value is converted to a String
-     * according to the rule defined by {@link String#valueOf(char[])}.
-     * </p>
-     * 
-     * @param ch The <code>char[]</code> value to append to this object.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified {@code char[]}.
+     * The {@code char[]} is converted to a string according to the rule
+     * defined by {@link String#valueOf(char[])}.
+     *
+     * @param ch
+     *            the {@code char[]} to append..
+     * @return this builder.
      * @see String#valueOf(char[])
      */
     public StringBuilder append(char[] ch) {
@@ -280,20 +251,20 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the subset of the
-     * <code>char[]</code> value passed. The <code>char[]</code> value is
-     * converted to a String according to the rule defined by
-     * {@link String#valueOf(char[],int,int)}.
-     * </p>
-     * 
-     * @param str The <code>char[]</code> value to append to this object.
-     * @param offset The inclusive offset index to begin copying from the
-     *        <code>str</code> parameter.
-     * @param len The number of character to copy from the <code>str</code>
-     *        parameter.
-     * @return A reference to this object.
-     * 
+     * Appends the string representation of the specified subset of the {@code
+     * char[]}. The {@code char[]} value is converted to a String according to
+     * the rule defined by {@link String#valueOf(char[],int,int)}.
+     *
+     * @param str
+     *            the {@code char[]} to append.
+     * @param offset
+     *            the inclusive offset index.
+     * @param len
+     *            the number of characters.
+     * @return this builder.
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code offset} and {@code len} do not specify a valid
+     *             subsequence.
      * @see String#valueOf(char[],int,int)
      */
     public StringBuilder append(char[] str, int offset, int len) {
@@ -302,15 +273,13 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the <code>CharSequence</code>
-     * value passed. If the <code>CharSequence</code> is <code>null</code>,
-     * then the String <code>"null"</code> is appended.
-     * </p>
-     * 
-     * @param csq The <code>CharSequence</code> value to append to this
-     *        object.
-     * @return A reference to this object.
+     * Appends the string representation of the specified {@code CharSequence}.
+     * If the {@code CharSequence} is {@code null}, then the string {@code
+     * "null"} is appended.
+     *
+     * @param csq
+     *            the {@code CharSequence} to append.
+     * @return this builder.
      */
     public StringBuilder append(CharSequence csq) {
         if (csq == null) {
@@ -322,18 +291,21 @@
     }
 
     /**
-     * <p>
-     * Appends the String representation of the subsequence of the
-     * <code>CharSequence</code> value passed. If the
-     * <code>CharSequence</code> is <code>null</code>, then the String
-     * <code>"null"</code> is used to extract the subsequence from.
-     * </p>
-     * 
-     * @param csq The <code>CharSequence</code> value to append to this
-     *        object.
-     * @param start The beginning index of the subsequence.
-     * @param end The ending index of the subsequence.
-     * @return A reference to this object.
+     * Appends the string representation of the specified subsequence of the
+     * {@code CharSequence}. If the {@code CharSequence} is {@code null}, then
+     * the string {@code "null"} is used to extract the subsequence from.
+     *
+     * @param csq
+     *            the {@code CharSequence} to append.
+     * @param start
+     *            the beginning index.
+     * @param end
+     *            the ending index.
+     * @return this builder.
+     * @throws IndexOutOfBoundsException
+     *             if {@code start} or {@code end} are negative, {@code start}
+     *             is greater than {@code end} or {@code end} is greater than
+     *             the length of {@code csq}.
      */
     public StringBuilder append(CharSequence csq, int start, int end) {
         append0(csq, start, end);
@@ -341,14 +313,12 @@
     }
 
     /**
-     * <p>
-     * Appends the encoded Unicode code point to this object. The code point is
-     * converted to a <code>char[]</code> as defined by
-     * {@link Character#toChars(int)}.
-     * </p>
-     * 
-     * @param codePoint The Unicode code point to encode and append.
-     * @return A reference to this object.
+     * Appends the encoded Unicode code point. The code point is converted to a
+     * {@code char[]} as defined by {@link Character#toChars(int)}.
+     *
+     * @param codePoint
+     *            the Unicode code point to encode and append.
+     * @return this builder.
      * @see Character#toChars(int)
      */
     public StringBuilder appendCodePoint(int codePoint) {
@@ -357,17 +327,17 @@
     }
 
     /**
-     * <p>
-     * Deletes a sequence of characters within this object, shifts any remaining
-     * characters to the left and adjusts the {@link #length()} of this object.
-     * </p>
+     * Deletes a sequence of characters specified by {@code start} and {@code
+     * end}. Shifts any remaining characters to the left.
      * 
-     * @param start The inclusive start index to begin deletion.
-     * @param end The exclusive end index to stop deletion.
-     * @return A reference to this object.
-     * @throws StringIndexOutOfBoundsException if <code>start</code> is less
-     *         than zero, greater than the current length or greater than
-     *         <code>end</code>.
+     * @param start
+     *            the inclusive start index.
+     * @param end
+     *            the exclusive end index.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code start} is less than zero, greater than the current
+     *             length or greater than {@code end}.
      */
     public StringBuilder delete(int start, int end) {
         delete0(start, end);
@@ -375,15 +345,15 @@
     }
 
     /**
-     * <p>
-     * Deletes a single character within this object, shifts any remaining
-     * characters to the left and adjusts the {@link #length()} of this object.
-     * </p>
+     * Deletes the character at the specified index. shifts any remaining
+     * characters to the left.
      * 
-     * @param index The index of the character to delete.
-     * @return A reference to this object.
-     * @throws StringIndexOutOfBoundsException if <code>index</code> is less
-     *         than zero or is greater than or equal to the current length.
+     * @param index
+     *            the index of the character to delete.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code index} is less than zero or is greater than or
+     *             equal to the current length.
      */
     public StringBuilder deleteCharAt(int index) {
         deleteCharAt0(index);
@@ -391,20 +361,19 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>boolean</code> value
-     * passed into this object at the <code>offset</code> passed. The
-     * <code>boolean</code> value is converted to a String according to the
-     * rule defined by {@link String#valueOf(boolean)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param b The <code>boolean</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code boolean} value
+     * at the specified {@code offset}. The {@code boolean} value is converted
+     * to a string according to the rule defined by
+     * {@link String#valueOf(boolean)}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param b
+     *            the {@code boolean} value to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length}.
      * @see String#valueOf(boolean)
      */
     public StringBuilder insert(int offset, boolean b) {
@@ -413,20 +382,18 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>char</code> value passed
-     * into this object at the <code>offset</code> passed. The
-     * <code>char</code> value is converted to a String according to the rule
-     * defined by {@link String#valueOf(char)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param c The <code>char</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws ArrayIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code char} value at
+     * the specified {@code offset}. The {@code char} value is converted to a
+     * string according to the rule defined by {@link String#valueOf(char)}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param c
+     *            the {@code char} value to insert.
+     * @return this builder.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      * @see String#valueOf(char)
      */
     public StringBuilder insert(int offset, char c) {
@@ -435,20 +402,18 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>int</code> value passed
-     * into this object at the <code>offset</code> passed. The
-     * <code>int</code> value is converted to a String according to the rule
-     * defined by {@link String#valueOf(int)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param i The <code>int</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code int} value at
+     * the specified {@code offset}. The {@code int} value is converted to a
+     * String according to the rule defined by {@link String#valueOf(int)}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param i
+     *            the {@code int} value to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      * @see String#valueOf(int)
      */
     public StringBuilder insert(int offset, int i) {
@@ -457,20 +422,18 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>long</code> value passed
-     * into this object at the <code>offset</code> passed. The
-     * <code>long</code> value is converted to a String according to the rule
-     * defined by {@link String#valueOf(long)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param l The <code>long</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code long} value at
+     * the specified {@code offset}. The {@code long} value is converted to a
+     * String according to the rule defined by {@link String#valueOf(long)}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param l
+     *            the {@code long} value to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {code length()}.
      * @see String#valueOf(long)
      */
     public StringBuilder insert(int offset, long l) {
@@ -479,20 +442,18 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>float</code> value
-     * passed into this object at the <code>offset</code> passed. The
-     * <code>float</code> value is converted to a String according to the rule
-     * defined by {@link String#valueOf(float)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param f The <code>float</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code float} value at
+     * the specified {@code offset}. The {@code float} value is converted to a
+     * string according to the rule defined by {@link String#valueOf(float)}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param f
+     *            the {@code float} value to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      * @see String#valueOf(float)
      */
     public StringBuilder insert(int offset, float f) {
@@ -501,20 +462,19 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>double</code> value
-     * passed into this object at the <code>offset</code> passed. The
-     * <code>double</code> value is converted to a String according to the
-     * rule defined by {@link String#valueOf(double)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param d The <code>double</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code double} value
+     * at the specified {@code offset}. The {@code double} value is converted
+     * to a String according to the rule defined by
+     * {@link String#valueOf(double)}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param d
+     *            the {@code double} value to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      * @see String#valueOf(double)
      */
     public StringBuilder insert(int offset, double d) {
@@ -523,20 +483,18 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>Object</code> value
-     * passed into this object at the <code>offset</code> passed. The
-     * <code>Object</code> value is converted to a String according to the
-     * rule defined by {@link String#valueOf(Object)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param obj The <code>Object</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code Object} at the
+     * specified {@code offset}. The {@code Object} value is converted to a
+     * String according to the rule defined by {@link String#valueOf(Object)}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param obj
+     *            the {@code Object} to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      * @see String#valueOf(Object)
      */
     public StringBuilder insert(int offset, Object obj) {
@@ -545,18 +503,17 @@
     }
 
     /**
-     * <p>
-     * Inserts the String value passed into this object at the
-     * <code>offset</code> passed. If the String parameter is null, then the
-     * String <code>"null"</code> is inserted.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param str The String to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
+     * Inserts the specified string at the specified {@code offset}. If the
+     * specified string is null, then the String {@code "null"} is inserted.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param str
+     *            the {@code String} to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      */
     public StringBuilder insert(int offset, String str) {
         insert0(offset, str);
@@ -564,20 +521,18 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>char[]</code> value
-     * passed into this object at the <code>offset</code> passed. The
-     * <code>char[]</code> value is converted to a String according to the
-     * rule defined by {@link String#valueOf(char[])}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param ch The <code>char[]</code> value to insert into this object.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code char[]} at the
+     * specified {@code offset}. The {@code char[]} value is converted to a
+     * String according to the rule defined by {@link String#valueOf(char[])}.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param ch
+     *            the {@code char[]} to insert.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      * @see String#valueOf(char[])
      */
     public StringBuilder insert(int offset, char[] ch) {
@@ -586,25 +541,24 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the subsequence of the
-     * <code>char[]</code> value passed into this object at the
-     * <code>offset</code> passed. The <code>char[]</code> value is
-     * converted to a String according to the rule defined by
+     * Inserts the string representation of the specified subsequence of the
+     * {@code char[]} at the specified {@code offset}. The {@code char[]} value
+     * is converted to a String according to the rule defined by
      * {@link String#valueOf(char[],int,int)}.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param str The <code>char[]</code> value to insert into this object.
-     * @param strOffset The inclusive index of the <code>str</code> parameter
-     *        to start copying from.
-     * @param strLen The number of characters to copy from the <code>str</code>
-     *        parameter.
-     * @return A reference to this object.
-     * 
-     * @throws StringIndexOutOfBoundsException if <code>offset</code> is
-     *         negative or greater than the current {@link #length()}.
-     * 
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param str
+     *            the {@code char[]} to insert.
+     * @param strOffset
+     *            the inclusive index.
+     * @param strLen
+     *            the number of characters.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}, or {@code strOffset} and {@code strLen} do
+     *             not specify a valid subsequence.
      * @see String#valueOf(char[],int,int)
      */
     public StringBuilder insert(int offset, char[] str, int strOffset,
@@ -614,22 +568,19 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the <code>CharSequence</code>
-     * value passed into this object at the <code>offset</code> passed. The
-     * <code>CharSequence</code> value is converted to a String as defined by
-     * {@link CharSequence#toString()}. If the <code>CharSequence</code> is
-     * <code>null</code>, then the String <code>"null"</code> is inserted.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param s The <code>CharSequence</code> value to insert into this
-     *        object.
-     * @return A reference to this object.
-     * 
-     * @throws IndexOutOfBoundsException if <code>offset</code> is negative or
-     *         greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified {@code CharSequence}
+     * at the specified {@code offset}. The {@code CharSequence} is converted
+     * to a String as defined by {@link CharSequence#toString()}. If {@code s}
+     * is {@code null}, then the String {@code "null"} is inserted.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param s
+     *            the {@code CharSequence} to insert.
+     * @return this builder.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}.
      * @see CharSequence#toString()
      */
     public StringBuilder insert(int offset, CharSequence s) {
@@ -638,27 +589,26 @@
     }
 
     /**
-     * <p>
-     * Inserts the String representation of the subsequence of the
-     * <code>CharSequence</code> value passed into this object at the
-     * <code>offset</code> passed. The <code>CharSequence</code> value is
-     * converted to a String as defined by
-     * {@link CharSequence#subSequence(int, int)}. If the
-     * <code>CharSequence</code> is <code>null</code>, then the String
-     * <code>"null"</code> is used to determine the subsequence.
-     * </p>
-     * 
-     * @param offset The index of this object to insert the value.
-     * @param s The <code>CharSequence</code> value to insert into this
-     *        object.
-     * @param start The start of the subsequence of the <code>s</code>
-     *        parameter.
-     * @param end The end of the subsequence of the <code>s</code> parameter.
-     * @return A reference to this object.
-     * 
-     * @throws IndexOutOfBoundsException if <code>offset</code> is negative or
-     *         greater than the current {@link #length()}.
-     * 
+     * Inserts the string representation of the specified subsequence of the
+     * {@code CharSequence} at the specified {@code offset}. The {@code
+     * CharSequence} is converted to a String as defined by
+     * {@link CharSequence#subSequence(int, int)}. If the {@code CharSequence}
+     * is {@code null}, then the string {@code "null"} is used to determine the
+     * subsequence.
+     *
+     * @param offset
+     *            the index to insert at.
+     * @param s
+     *            the {@code CharSequence} to insert.
+     * @param start
+     *            the start of the subsequence of the character sequence.
+     * @param end
+     *            the end of the subsequence of the character sequence.
+     * @return this builder.
+     * @throws IndexOutOfBoundsException
+     *             if {@code offset} is negative or greater than the current
+     *             {@code length()}, or {@code start} and {@code end} do not
+     *             specify a valid subsequence.
      * @see CharSequence#subSequence(int, int)
      */
     public StringBuilder insert(int offset, CharSequence s, int start, int end) {
@@ -667,23 +617,21 @@
     }
 
     /**
-     * <p>
-     * Replaces the indicated subsequence of this object with the String passed.
-     * If the String passed is longer or shorter than the subsequence, then this
-     * object will be adjusted appropriately.
-     * </p>
+     * Replaces the specified subsequence in this builder with the specified
+     * string.
      * 
-     * @param start The inclusive start index of the sequence to replace in this
-     *        object.
-     * @param end The exclusive end index of the sequence to replace in this
-     *        object.
-     * @param str The String to replace the subsequence.
-     * @return A reference to this object.
-     * @throws StringIndexOutOfBoundsException if <code>start</code> is
-     *         negative, greater than the current {@link #length()} or greater
-     *         than <code>end</code>.
-     * @throws NullPointerException if the <code>str</code> parameter is
-     *         <code>null</code>.
+     * @param start
+     *            the inclusive begin index.
+     * @param end
+     *            the exclusive end index.
+     * @param str
+     *            the replacement string.
+     * @return this builder.
+     * @throws StringIndexOutOfBoundsException
+     *             if {@code start} is negative, greater than the current
+     *             {@code length()} or greater than {@code end}.
+     * @throws NullPointerException
+     *            if {@code str} is {@code null}.
      */
     public StringBuilder replace(int start, int end, String str) {
         replace0(start, end, str);
@@ -691,11 +639,9 @@
     }
 
     /**
-     * <p>
-     * Reverses the contents of this object.
-     * </p>
+     * Reverses the order of characters in this builder.
      * 
-     * @return A reference to this object.
+     * @return this buffer.
      */
     public StringBuilder reverse() {
         reverse0();
@@ -703,9 +649,9 @@
     }
 
     /**
-     * Answers the contents of this StringBuilder.
+     * Returns the contents of this builder.
      * 
-     * @return a String containing the characters in this StringBuilder
+     * @return the string representation of the data in this builder.
      */
     @Override
     public String toString() {
@@ -718,14 +664,15 @@
     }
 
     /**
-     * <p>
-     * Reads the state of a <code>StringBuilder</code> from the passed stream
-     * and restores it to this instance.
-     * </p>
-     * 
-     * @param in The stream to read the state from.
-     * @throws IOException if the stream throws it during the read.
-     * @throws ClassNotFoundException if the stream throws it during the read.
+     * Reads the state of a {@code StringBuilder} from the passed stream and
+     * restores it to this instance.
+     *
+     * @param in
+     *            the stream to read the state from.
+     * @throws IOException
+     *             if the stream throws it during the read.
+     * @throws ClassNotFoundException
+     *             if the stream throws it during the read.
      */
     private void readObject(ObjectInputStream in) throws IOException,
             ClassNotFoundException {
@@ -736,15 +683,15 @@
     }
 
     /**
-     * <p>
      * Writes the state of this object to the stream passed.
-     * </p>
-     * 
-     * @param out The stream to write the state to.
-     * @throws IOException if the stream throws it during the write.
-     * @serialData <code>int</code> - The length of this object.
-     *             <code>char[]</code> - The buffer from this object, which
-     *             may be larger than the length field.
+     *
+     * @param out
+     *            the stream to write the state to.
+     * @throws IOException
+     *             if the stream throws it during the write.
+     * @serialData {@code int} - the length of this object. {@code char[]} - the
+     *             buffer from this object, which may be larger than the length
+     *             field.
      */
     private void writeObject(ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringIndexOutOfBoundsException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringIndexOutOfBoundsException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringIndexOutOfBoundsException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StringIndexOutOfBoundsException.java Sat May  2 08:09:50 2009
@@ -21,40 +21,41 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This runtime exception is thrown when the a String is indexed with a value
- * less than zero, or greater than or equal to the size of the array.
+ * Thrown when the a string is indexed with a value less than zero, or greater
+ * than or equal to the size of the array.
  */
 public class StringIndexOutOfBoundsException extends IndexOutOfBoundsException {
 
     private static final long serialVersionUID = -6762910422159637258L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public StringIndexOutOfBoundsException() {
-		super();
-	}
+     * Constructs a new {@code StringIndexOutOfBoundsException} that includes
+     * the current stack trace.
+     */
+    public StringIndexOutOfBoundsException() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * (which is based on the argument which is the index which failed) filled
-	 * in.
-	 * 
-	 * @param index
-	 *            int the index which is out of bounds
-	 */
-	public StringIndexOutOfBoundsException(int index) {
-		super(Msg.getString("K0055", index)); //$NON-NLS-1$
-	}
+    /**
+     * Constructs a new {@code StringIndexOutOfBoundsException} with the current
+     * stack trace and a detail message that is based on the specified invalid
+     * {@code index}.
+     * 
+     * @param index
+     *            the index which is out of bounds.
+     */    
+    public StringIndexOutOfBoundsException(int index) {
+        super(Msg.getString("K0055", index)); //$NON-NLS-1$
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public StringIndexOutOfBoundsException(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code StringIndexOutOfBoundsException} with the current
+     * stack trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public StringIndexOutOfBoundsException(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SuppressWarnings.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SuppressWarnings.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SuppressWarnings.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SuppressWarnings.java Sat May  2 08:09:50 2009
@@ -22,9 +22,14 @@
 import java.lang.annotation.Target;
 
 /**
- * An annotation that indicates a compiler should suppress any warnings of the
- * type specified in the {@link #value()}.
- * 
+ * Annotation type used to indicate that the compiler should not issue the
+ * specified warnings for the marked program element. Warnings are not only
+ * suppressed for the annotated element but also for all program elements
+ * contained in that element.
+ * <p>
+ * It is recommended that programmers always use this annotation on the most
+ * deeply nested element where it is actually needed.
+ *
  * @since 1.5
  */
 @Target( { ElementType.TYPE, ElementType.FIELD, ElementType.METHOD,
@@ -34,10 +39,7 @@
 public @interface SuppressWarnings {
 
     /**
-     * Answers the array of warnings that compilers should suppress for the
-     * annotated element.
-     * 
-     * @return an array of warning types to suppress.
+     * The list of warnings a compiler should not issue.
      */
     public String[] value();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadDeath.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadDeath.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadDeath.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadDeath.java Sat May  2 08:09:50 2009
@@ -17,7 +17,6 @@
 
 package java.lang;
 
-
 /**
  * ThreadDeath is thrown when a thread stops executing. It is used to aid in the
  * orderly unrolling of the thread's stack (eg. cleanup of monitors).
@@ -27,10 +26,10 @@
     private static final long serialVersionUID = -4417128565033088268L;
 
     /**
-	 * Constructs a new instance of this class. Note that in the case of
-	 * ThreadDeath, the walkback may <em>not</em> be filled in a way which
-	 * allows a stack trace to be printed.
-	 */
-	public ThreadDeath() {
-	}
+     * Constructs a new instance of this class. Note that in the case of
+     * ThreadDeath, the stacktrace may <em>not</em> be filled in a way which
+     * allows a stack trace to be printed.
+     */
+    public ThreadDeath() {
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadLocal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadLocal.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadLocal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ThreadLocal.java Sat May  2 08:09:50 2009
@@ -24,23 +24,29 @@
  */
 
 /**
- * A ThreadLocal is a variable that has a per-thread value. Different Threads
- * may reference the same ThreadLocal object, but the values they observe will
- * not be <code>==</code>. This provides Thread local storage.
- * 
+ * Implements a thread-local storage, that is, a variable for which each thread
+ * has its own value. All threads share the same {@code ThreadLocal} object,
+ * but each sees a different value when accessing it, and changes made by one
+ * thread do not affect the other threads. The implementation supports
+ * {@code null} values.
+ *
  * @see java.lang.Thread
  */
 public class ThreadLocal<T> {
     /**
-     * Constructs a new ThreadLocal object
+     * Creates a new thread-local variable.
      */
     public ThreadLocal() {
         super();
     }
 
     /**
-     * Return the value of this variable under
-     * <code>Thread.currentThread()</code>
+     * Returns the value of this variable for the current thread. If an entry
+     * doesn't yet exist for this variable on this thread, this method will
+     * create an entry, populating the value with the result of
+     * {@link #initialValue()}.
+     *
+     * @return the current value of the variable for the calling thread.
      */
     @SuppressWarnings("unchecked")
     public T get() {
@@ -48,26 +54,32 @@
     }
 
     /**
-     * Return the initial value of this variable under
-     * <code>Thread.currentThread()</code>
+     * Provides the initial value of this variable for the current thread.
+     * The default implementation returns {@code null}.
+     *
+     * @return the initial value of the variable.
      */
     protected T initialValue() {
         return null;
     }
 
     /**
-     * Set the value of this variable under <code>Thread.currentThread()</code>
+     * Sets the value of this variable for the current thread. If set to
+     * {@code null}, the value will be set to null and the underlying entry will
+     * still be present.
+     *
+     * @param value the new value of the variable for the caller thread.
      */
     public void set(T value) {
         Thread.currentThread().setThreadLocal(this, value);
     }
 
     /**
-     * <p>
-     * Removes the current value, such that the next call to {@link #get()} will
-     * return the default value, as defined by {@link #initialValue()}.
-     * </p>
-     * 
+     * Removes the entry for this variable in the current thread. If this call
+     * is followed by a {@link #get()} before a {@link #set},
+     * {@code #get()} will call {@link #initialValue()} and create a new
+     * entry with the resulting value.
+     *
      * @since 1.5
      */
     public void remove() {



Mime
View raw message