Return-Path: 
 <commits-return-58303-apmail-harmony-commits-archive=harmony.apache.org@harmony.apache.org>
Delivered-To: apmail-harmony-commits-archive@www.apache.org
Received: (qmail 62697 invoked from network); 2 May 2009 08:11:40 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 2 May 2009 08:11:40 -0000
Received: (qmail 42786 invoked by uid 500); 2 May 2009 08:11:39 -0000
Delivered-To: apmail-harmony-commits-archive@harmony.apache.org
Received: (qmail 42735 invoked by uid 500); 2 May 2009 08:11:39 -0000
Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@harmony.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@harmony.apache.org>
List-Post: <mailto:commits@harmony.apache.org>
List-Id: <commits.harmony.apache.org>
Reply-To: dev@harmony.apache.org
Delivered-To: mailing list commits@harmony.apache.org
Received: (qmail 42726 invoked by uid 99); 2 May 2009 08:11:39 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 02 May 2009 08:11:39 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 02 May 2009 08:11:34 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id 7866B2388D0A; Sat,  2 May 2009 08:10:52 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r770909 [8/10] - in
 /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang: ./
 ref/ reflect/
Date: Sat, 02 May 2009 08:09:57 -0000
To: commits@harmony.apache.org
From: tellison@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20090502081052.7866B2388D0A@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/String.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/String.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/String.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/String.java Sat May  2 08:09:50 2009
@@ -37,13 +37,11 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * <p>
- * An immutable sequence of characters/code units (<code>char</code>s). A
- * <code>String</code> is represented by array of UTF-16 values, such that
+ * An immutable sequence of characters/code units ({@code char}s). A
+ * {@code String} is represented by array of UTF-16 values, such that
  * Unicode supplementary characters (code points) are stored/encoded as
- * surrogate pairs via Unicode code units (<code>char</code>)
- * </p>
- * 
+ * surrogate pairs via Unicode code units ({@code char}).
+ *
  * @see StringBuffer
  * @see StringBuilder
  * @see Charset
@@ -85,9 +83,9 @@
         /**
          * Override the print(String) method from PrintStream to perform the
          * character conversion using the console character converter.
-         * 
+         *
          * @param str
-         *            the String to convert
+         *            the string to convert
          */
         @Override
         public void print(String str) {
@@ -113,24 +111,24 @@
 
         /**
          * Compare the two objects to determine the relative ordering.
-         * 
+         *
          * @param o1
          *            an Object to compare
          * @param o2
          *            an Object to compare
          * @return an int < 0 if object1 is less than object2, 0 if they are
          *         equal, and > 0 if object1 is greater
-         * 
+         *
          * @exception ClassCastException
-         *                when objects are not the correct type
+         *                if objects are not the correct type
          */
         public int compare(String o1, String o2) {
             return o1.compareToIgnoreCase(o2);
         }
     }
 
-    /*
-     * A Comparator which compares Strings ignoring the case of the characters.
+    /**
+     * A comparator ignoring the case of the characters.
      */
     public static final Comparator<String> CASE_INSENSITIVE_ORDER = new CaseInsensitiveComparator();
 
@@ -156,7 +154,7 @@
     }
 
     /**
-     * Answers an empty string.
+     * Creates an empty string.
      */
     public String() {
         value = new char[0];
@@ -174,48 +172,30 @@
     }
 
     /**
-     * Converts the byte array to a String using the default encoding as
+     * Converts the byte array to a string using the default encoding as
      * specified by the file.encoding system property. If the system property is
      * not defined, the default encoding is ISO8859_1 (ISO-Latin-1). If 8859-1
      * is not available, an ASCII encoding is used.
      * 
      * @param data
-     *            the byte array to convert to a String
-     * 
-     * @throws NullPointerException
-     *             when data is null
-     * 
-     * @see #getBytes()
-     * @see #getBytes(int, int, byte[], int)
-     * @see #getBytes(String)
-     * @see #valueOf(boolean)
-     * @see #valueOf(char)
-     * @see #valueOf(char[])
-     * @see #valueOf(char[], int, int)
-     * @see #valueOf(double)
-     * @see #valueOf(float)
-     * @see #valueOf(int)
-     * @see #valueOf(long)
-     * @see #valueOf(Object)
-     * 
+     *            the byte array to convert to a string.
      */
     public String(byte[] data) {
         this(data, 0, data.length);
     }
 
     /**
-     * Converts the byte array to a String, setting the high byte of every
+     * Converts the byte array to a string, setting the high byte of every
      * character to the specified value.
      * 
      * @param data
-     *            the byte array to convert to a String
+     *            the byte array to convert to a string.
      * @param high
-     *            the high byte to use
-     * 
+     *            the high byte to use.
      * @throws NullPointerException
-     *             when data is null
-     * 
-     * @deprecated Use String(byte[]) or String(byte[], String) instead
+     *             when {@code data} is {@code null}.
+     * @deprecated Use {@link #String(byte[])} or
+     *             {@link #String(byte[], String)} instead.
      */
     @Deprecated
     public String(byte[] data, int high) {
@@ -223,36 +203,22 @@
     }
 
     /**
-     * Converts the byte array to a String using the default encoding as
+     * Converts the byte array to a string using the default encoding as
      * specified by the file.encoding system property. If the system property is
      * not defined, the default encoding is ISO8859_1 (ISO-Latin-1). If 8859-1
      * is not available, an ASCII encoding is used.
      * 
      * @param data
-     *            the byte array to convert to a String
+     *            the byte array to convert to a string.
      * @param start
-     *            the starting offset in the byte array
+     *            the starting offset in the byte array.
      * @param length
-     *            the number of bytes to convert
-     * 
-     * @throws IndexOutOfBoundsException
-     *             when <code>length < 0, start < 0</code> or
-     *             <code>start + length > data.length</code>
+     *            the number of bytes to convert.
      * @throws NullPointerException
-     *             when data is null
-     * 
-     * @see #getBytes()
-     * @see #getBytes(int, int, byte[], int)
-     * @see #getBytes(String)
-     * @see #valueOf(boolean)
-     * @see #valueOf(char)
-     * @see #valueOf(char[])
-     * @see #valueOf(char[], int, int)
-     * @see #valueOf(double)
-     * @see #valueOf(float)
-     * @see #valueOf(int)
-     * @see #valueOf(long)
-     * @see #valueOf(Object)
+     *             when {@code data} is {@code null}.
+     * @throws IndexOutOfBoundsException
+     *             if {@code length < 0, start < 0} or {@code start + length >
+     *             data.length}.
      */
     public String(byte[] data, int start, int length) {
         // start + length could overflow, start/length maybe MaxInt
@@ -275,25 +241,24 @@
     }
 
     /**
-     * Converts the byte array to a String, setting the high byte of every
+     * Converts the byte array to a string, setting the high byte of every
      * character to the specified value.
-     * 
+     *
      * @param data
-     *            the byte array to convert to a String
+     *            the byte array to convert to a string.
      * @param high
-     *            the high byte to use
+     *            the high byte to use.
      * @param start
-     *            the starting offset in the byte array
+     *            the starting offset in the byte array.
      * @param length
-     *            the number of bytes to convert
-     * 
-     * @throws IndexOutOfBoundsException
-     *             when <code>length < 0, start < 0</code> or
-     *             <code>start + length > data.length</code>
+     *            the number of bytes to convert.
      * @throws NullPointerException
-     *             when data is null
-     * 
-     * @deprecated Use String(byte[], int, int) instead
+     *             when {@code data} is {@code null}.
+     * @throws IndexOutOfBoundsException
+     *             if {@code length < 0, start < 0} or
+     *             {@code start + length > data.length}
+     *
+     * @deprecated Use {@link #String(byte[], int, int)} instead.
      */
     @Deprecated
     public String(byte[] data, int high, int start, int length) {
@@ -316,38 +281,23 @@
     }
 
     /**
-     * Converts the byte array to a String using the specified encoding.
+     * Converts the byte array to a string using the specified encoding.
      * 
      * @param data
-     *            the byte array to convert to a String
+     *            the byte array to convert to a string.
      * @param start
-     *            the starting offset in the byte array
+     *            the starting offset in the byte array.
      * @param length
-     *            the number of bytes to convert
+     *            the number of bytes to convert.
      * @param encoding
-     *            the encoding
-     * 
+     *            the encoding.
+     * @throws NullPointerException
+     *             when {@code data} is {@code null}.
      * @throws IndexOutOfBoundsException
-     *             when <code>length < 0, start < 0</code> or
-     *             <code>start + length > data.length</code>
+     *             if {@code length < 0, start < 0} or {@code start + length >
+     *             data.length}.
      * @throws UnsupportedEncodingException
-     *             when encoding is not supported
-     * @throws NullPointerException
-     *             when data is null
-     * 
-     * @see #getBytes()
-     * @see #getBytes(int, int, byte[], int)
-     * @see #getBytes(String)
-     * @see #valueOf(boolean)
-     * @see #valueOf(char)
-     * @see #valueOf(char[])
-     * @see #valueOf(char[], int, int)
-     * @see #valueOf(double)
-     * @see #valueOf(float)
-     * @see #valueOf(int)
-     * @see #valueOf(long)
-     * @see #valueOf(Object)
-     * @see UnsupportedEncodingException
+     *             if {@code encoding} is not supported.
      */
     public String(byte[] data, int start, int length, final String encoding)
             throws UnsupportedEncodingException {
@@ -381,68 +331,51 @@
     }
 
     /**
-     * Converts the byte array to a String using the specified encoding.
+     * Converts the byte array to a string using the specified encoding.
      * 
      * @param data
-     *            the byte array to convert to a String
+     *            the byte array to convert to a string.
      * @param encoding
-     *            the encoding
-     * 
-     * @throws UnsupportedEncodingException
-     *             when encoding is not supported
+     *            the encoding.
      * @throws NullPointerException
-     *             when data is null
-     * 
-     * @see #getBytes()
-     * @see #getBytes(int, int, byte[], int)
-     * @see #getBytes(String)
-     * @see #valueOf(boolean)
-     * @see #valueOf(char)
-     * @see #valueOf(char[])
-     * @see #valueOf(char[], int, int)
-     * @see #valueOf(double)
-     * @see #valueOf(float)
-     * @see #valueOf(int)
-     * @see #valueOf(long)
-     * @see #valueOf(Object)
-     * @see UnsupportedEncodingException
+     *             when {@code data} is {@code null}.
+     * @throws UnsupportedEncodingException
+     *             if {@code encoding} is not supported.
      */
     public String(byte[] data, String encoding) throws UnsupportedEncodingException {
         this(data, 0, data.length, encoding);
     }
 
     /**
-     * Initializes this String to contain the characters in the specified
-     * character array. Modifying the character array after creating the String
-     * has no effect on the String.
+     * Initializes this string to contain the characters in the specified
+     * character array. Modifying the character array after creating the string
+     * has no effect on the string.
      * 
      * @param data
-     *            the array of characters
-     * 
+     *            the array of characters.
      * @throws NullPointerException
-     *             when data is null
+     *             when {@code data} is {@code null}.
      */
     public String(char[] data) {
         this(data, 0, data.length);
     }
 
     /**
-     * Initializes this String to contain the specified characters in the
-     * character array. Modifying the character array after creating the String
-     * has no effect on the String.
+     * Initializes this string to contain the specified characters in the
+     * character array. Modifying the character array after creating the string
+     * has no effect on the string.
      * 
      * @param data
-     *            the array of characters
+     *            the array of characters.
      * @param start
-     *            the starting offset in the character array
+     *            the starting offset in the character array.
      * @param length
-     *            the number of characters to use
-     * 
-     * @throws IndexOutOfBoundsException
-     *             when <code>length < 0, start < 0</code> or
-     *             <code>start + length > data.length</code>
+     *            the number of characters to use.
      * @throws NullPointerException
-     *             when data is null
+     *             when {@code data} is {@code null}.
+     * @throws IndexOutOfBoundsException
+     *             if {@code length < 0, start < 0} or {@code start + length >
+     *             data.length}
      */
     public String(char[] data, int start, int length) {
         // range check everything so a new char[] is not created
@@ -468,10 +401,10 @@
     }
 
     /**
-     * Creates a string that is a copy of another string
+     * Creates a {@code String} that is a copy of the specified string.
      * 
      * @param string
-     *            the String to copy
+     *            the string to copy.
      */
     public String(String string) {
         value = string.value;
@@ -480,10 +413,11 @@
     }
 
     /**
-     * Creates a string from the contents of a StringBuffer.
+     * Creates a {@code String} from the contents of the specified
+     * {@code StringBuffer}.
      * 
      * @param stringbuffer
-     *            the StringBuffer
+     *            the buffer to get the contents from.
      */
     public String(StringBuffer stringbuffer) {
         offset = 0;
@@ -494,26 +428,23 @@
     }
 
     /**
-     * <p>
-     * Constructs a <code>String</code> from the sub-array of Unicode code
-     * points.
-     * </p>
-     * 
+     * Creates a {@code String} from the sub-array of Unicode code points.
+     *
      * @param codePoints
-     *            The array of Unicode code points to convert.
+     *            the array of Unicode code points to convert.
      * @param offset
-     *            The inclusive index into <code>codePoints</code> to begin
+     *            the inclusive index into {@code codePoints} to begin
      *            converting from.
      * @param count
-     *            The number of element in <code>codePoints</code> to copy.
+     *            the number of elements in {@code codePoints} to copy.
      * @throws NullPointerException
-     *             if <code>codePoints</code> is null.
+     *             if {@code codePoints} is {@code null}.
      * @throws IllegalArgumentException
-     *             if any of the elements of <code>codePoints</code> are not
-     *             valid Unicode code points.
+     *             if any of the elements of {@code codePoints} are not valid
+     *             Unicode code points.
      * @throws IndexOutOfBoundsException
-     *             if <code>offset</code> or <code>count</code> are not
-     *             within the bounds of <code>codePoints</code>.
+     *             if {@code offset} or {@code count} are not within the bounds
+     *             of {@code codePoints}.
      * @since 1.5
      */
     public String(int[] codePoints, int offset, int count) {
@@ -536,14 +467,13 @@
     }
 
     /**
-     * <p>
-     * Constructs a <code>String</code> from a <code>StringBuilder</code>.
-     * </p>
+     * Creates a {@code String} from the contents of the specified {@code
+     * StringBuilder}.
      * 
      * @param sb
-     *            The StringBuilder to copy from.
+     *            the {@code StringBuilder} to copy the contents from.
      * @throws NullPointerException
-     *             if <code>sb</code> is <code>null</code>.
+     *             if {@code sb} is {@code null}.
      * @since 1.5
      */
     public String(StringBuilder sb) {
@@ -557,7 +487,7 @@
     }
 
     /*
-     * Creates a string that is s1 + v1. May be used by JIT code.
+     * Creates a {@code String} that is s1 + v1. May be used by JIT code.
      */
     @SuppressWarnings("unused")
     private String(String s1, int v1) {
@@ -574,15 +504,13 @@
     }
 
     /**
-     * Answers the character at the specified offset in this String.
+     * Returns the character at the specified offset in this string.
      * 
      * @param index
-     *            the zero-based index in this string
-     * @return the character at the index
-     * 
+     *            the zero-based index in this string.
+     * @return the character at the index.
      * @throws IndexOutOfBoundsException
-     *             when <code>index < 0</code> or
-     *             <code>index >= length()</code>
+     *             if {@code index < 0} or {@code index >= length()}.
      */
     public char charAt(int index) {
         if (0 <= index && index < count) {
@@ -625,25 +553,24 @@
     }
 
     /**
-     * Compares the specified String to this String using the Unicode values of
-     * the characters. Answer 0 if the strings contain the same characters in
-     * the same order. Answer a negative integer if the first non-equal
-     * character in this String has a Unicode value which is less than the
+     * Compares the specified string to this string using the Unicode values of
+     * the characters. Returns 0 if the strings contain the same characters in
+     * the same order. Returns a negative integer if the first non-equal
+     * character in this string has a Unicode value which is less than the
      * Unicode value of the character at the same position in the specified
-     * string, or if this String is a prefix of the specified string. Answer a
-     * positive integer if the first non-equal character in this String has a
+     * string, or if this string is a prefix of the specified string. Returns a
+     * positive integer if the first non-equal character in this string has a
      * Unicode value which is greater than the Unicode value of the character at
-     * the same position in the specified string, or if the specified String is
-     * a prefix of the this String.
+     * the same position in the specified string, or if the specified string is
+     * a prefix of this string.
      * 
      * @param string
-     *            the string to compare
-     * @return 0 if the strings are equal, a negative integer if this String is
-     *         before the specified String, or a positive integer if this String
-     *         is after the specified String
-     * 
+     *            the string to compare.
+     * @return 0 if the strings are equal, a negative integer if this string is
+     *         before the specified string, or a positive integer if this string
+     *         is after the specified string.
      * @throws NullPointerException
-     *             when string is null
+     *             if {@code string} is {@code null}.
      */
     public int compareTo(String string) {
         // Code adapted from K&R, pg 101
@@ -659,13 +586,24 @@
     }
 
     /**
-     * Compare the receiver to the specified String to determine the relative
-     * ordering when the case of the characters is ignored.
+     * Compares the specified string to this string using the Unicode values of
+     * the characters, ignoring case differences. Returns 0 if the strings
+     * contain the same characters in the same order. Returns a negative integer
+     * if the first non-equal character in this string has a Unicode value which
+     * is less than the Unicode value of the character at the same position in
+     * the specified string, or if this string is a prefix of the specified
+     * string. Returns a positive integer if the first non-equal character in
+     * this string has a Unicode value which is greater than the Unicode value
+     * of the character at the same position in the specified string, or if the
+     * specified string is a prefix of this string.
      * 
      * @param string
-     *            a String
-     * @return an int < 0 if this String is less than the specified String, 0 if
-     *         they are equal, and > 0 if this String is greater
+     *            the string to compare.
+     * @return 0 if the strings are equal, a negative integer if this string is
+     *         before the specified string, or a positive integer if this string
+     *         is after the specified string.
+     * @throws NullPointerException
+     *             if {@code string} is {@code null}.
      */
     public int compareToIgnoreCase(String string) {
         int o1 = offset, o2 = string.offset, result;
@@ -686,15 +624,12 @@
     }
 
     /**
-     * Concatenates this String and the specified string.
+     * Concatenates this string and the specified string.
      * 
      * @param string
      *            the string to concatenate
-     * @return a new String which is the concatenation of this String and the
-     *         specified String
-     * 
-     * @throws NullPointerException
-     *             if string is null
+     * @return a new string which is the concatenation of this string and the
+     *         specified string.
      */
     public String concat(String string) {
         if (string.count > 0 && count > 0) {
@@ -708,39 +643,37 @@
     }
 
     /**
-     * Creates a new String containing the characters in the specified character
-     * array. Modifying the character array after creating the String has no
-     * effect on the String.
+     * Creates a new string containing the characters in the specified character
+     * array. Modifying the character array after creating the string has no
+     * effect on the string.
      * 
      * @param data
-     *            the array of characters
-     * @return the new String
-     * 
+     *            the array of characters.
+     * @return the new string.
      * @throws NullPointerException
-     *             if data is null
+     *             if {@code data} is {@code null}.
      */
     public static String copyValueOf(char[] data) {
         return new String(data, 0, data.length);
     }
 
     /**
-     * Creates a new String containing the specified characters in the character
-     * array. Modifying the character array after creating the String has no
-     * effect on the String.
+     * Creates a new string containing the specified characters in the character
+     * array. Modifying the character array after creating the string has no
+     * effect on the string.
      * 
      * @param data
-     *            the array of characters
+     *            the array of characters.
      * @param start
-     *            the starting offset in the character array
+     *            the starting offset in the character array.
      * @param length
-     *            the number of characters to use
-     * @return the new String
-     * 
-     * @throws IndexOutOfBoundsException
-     *             if <code>length < 0, start < 0</code> or
-     *             <code>start + length > data.length</code>
+     *            the number of characters to use.
+     * @return the new string.
      * @throws NullPointerException
-     *             if data is null
+     *             if {@code data} is {@code null}.
+     * @throws IndexOutOfBoundsException
+     *             if {@code length < 0, start < 0} or {@code start + length >
+     *             data.length}.
      */
     public static String copyValueOf(char[] data, int start, int length) {
         return new String(data, start, length);
@@ -769,31 +702,29 @@
     }
 
     /**
-     * Compares the specified string to this String to determine if the
+     * Compares the specified string to this string to determine if the
      * specified string is a suffix.
      * 
      * @param suffix
-     *            the string to look for
-     * @return true when the specified string is a suffix of this String, false
-     *         otherwise
-     * 
+     *            the suffix to look for.
+     * @return {@code true} if the specified string is a suffix of this string,
+     *         {@code false} otherwise.
      * @throws NullPointerException
-     *             if suffix is null
+     *             if {@code suffix} is {@code null}.
      */
     public boolean endsWith(String suffix) {
         return regionMatches(count - suffix.count, suffix, 0, suffix.count);
     }
 
     /**
-     * Compares the specified object to this String and answer if they are
-     * equal. The object must be an instance of String with the same characters
+     * Compares the specified object to this string and returns true if they are
+     * equal. The object must be an instance of string with the same characters
      * in the same order.
      * 
      * @param object
-     *            the object to compare
-     * @return true if the specified object is equal to this String, false
-     *         otherwise
-     * 
+     *            the object to compare.
+     * @return {@code true} if the specified object is equal to this string,
+     *         {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -813,13 +744,13 @@
     }
 
     /**
-     * Compares the specified String to this String ignoring the case of the
-     * characters and answer if they are equal.
+     * Compares the specified string to this string ignoring the case of the
+     * characters and returns true if they are equal.
      * 
      * @param string
-     *            the string to compare
-     * @return true if the specified string is equal to this String, false
-     *         otherwise
+     *            the string to compare.
+     * @return {@code true} if the specified string is equal to this string,
+     *         {@code false} otherwise.
      */
     public boolean equalsIgnoreCase(String string) {
         if (string == this) {
@@ -845,14 +776,12 @@
     }
 
     /**
-     * Converts this String to a byte encoding using the default encoding as
+     * Converts this string to a byte array using the default encoding as
      * specified by the file.encoding system property. If the system property is
      * not defined, the default encoding is ISO8859_1 (ISO-Latin-1). If 8859-1
      * is not available, an ASCII encoding is used.
      * 
-     * @return the byte array encoding of this String
-     * 
-     * @see String
+     * @return the byte array encoding of this string.
      */
     public byte[] getBytes() {
         ByteBuffer buffer = defaultCharset().encode(
@@ -863,25 +792,23 @@
     }
 
     /**
-     * Converts this String to a byte array, ignoring the high order bits of
+     * Converts this string to a byte array, ignoring the high order bits of
      * each character.
      * 
      * @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 data
-     *            the destination byte array
+     *            the destination byte array.
      * @param index
-     *            the starting offset in the byte array
-     * 
+     *            the starting offset in the destination byte array.
      * @throws NullPointerException
-     *             when data is null
+     *             if {@code data} is {@code null}.
      * @throws IndexOutOfBoundsException
-     *             when
-     *             <code>start < 0, end > length(), index < 0, end - start > data.length - index</code>
-     * 
-     * @deprecated Use getBytes() or getBytes(String)
+     *             if {@code start < 0}, {@code end > length()}, {@code index <
+     *             0} or {@code end - start > data.length - index}.
+     * @deprecated Use {@link #getBytes()} or {@link #getBytes(String)}
      */
     @Deprecated
     public void getBytes(int start, int end, byte[] data, int index) {
@@ -900,17 +827,13 @@
     }
 
     /**
-     * Converts this String to a byte encoding using the specified encoding.
+     * Converts this string to a byte array using the specified encoding.
      * 
      * @param encoding
-     *            the encoding
-     * @return the byte array encoding of this String
-     * 
+     *            the encoding to use.
+     * @return the encoded byte array of this string.
      * @throws UnsupportedEncodingException
-     *             when the encoding is not supported
-     * 
-     * @see String
-     * @see UnsupportedEncodingException
+     *             if the encoding is not supported.
      */
     public byte[] getBytes(String encoding) throws UnsupportedEncodingException {
         ByteBuffer buffer = getCharset(encoding).encode(
@@ -939,23 +862,23 @@
     }
 
     /**
-     * Copies the specified characters in this String to the character array
+     * Copies the specified characters in this string to the character array
      * starting at the specified offset in the character array.
      * 
      * @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
+     *            the destination character array.
      * @param index
-     *            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>
+     *            the starting offset in the character array.
      * @throws NullPointerException
-     *             when buffer is null
+     *             if {@code buffer} is {@code null}.
+     * @throws IndexOutOfBoundsException
+     *             if {@code start < 0}, {@code end > length()}, {@code start >
+     *             end}, {@code index < 0}, {@code end - start > buffer.length -
+     *             index}
      */
     public void getChars(int start, int end, char[] buffer, int index) {
         // NOTE last character not copied!
@@ -967,14 +890,6 @@
         }
     }
 
-    /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
-     * 
-     * @see #equals
-     */
     @Override
     public int hashCode() {
         if (hashCode == 0) {
@@ -990,40 +905,30 @@
     }
 
     /**
-     * Searches in this String for the first index of the specified character.
+     * Searches in this string for the first index of the specified character.
      * The search for the character starts at the beginning and moves towards
-     * the end of this String.
+     * the end of this string.
      * 
      * @param c
-     *            the character to find
-     * @return the index in this String of the specified character, -1 if the
-     *         character isn't found
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *            the character to find.
+     * @return the index in this string of the specified character, -1 if the
+     *         character isn't found.
      */
     public int indexOf(int c) {
         return indexOf(c, 0);
     }
 
     /**
-     * Searches in this String for the index of the specified character. The
+     * Searches in this string for the index of the specified character. The
      * search for the character starts at the specified offset and moves towards
-     * the end of this String.
+     * the end of this string.
      * 
      * @param c
-     *            the character to find
+     *            the character to find.
      * @param start
-     *            the starting offset
-     * @return the index in this String of the specified character, -1 if the
-     *         character isn't found
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *            the starting offset.
+     * @return the index in this string of the specified character, -1 if the
+     *         character isn't found.
      */
     public int indexOf(int c, int start) {
         if (start < count) {
@@ -1040,46 +945,34 @@
     }
 
     /**
-     * Searches in this String for the first index of the specified string. The
+     * Searches in this string for the first index of the specified string. The
      * search for the string starts at the beginning and moves towards the end
-     * of this String.
+     * of this string.
      * 
      * @param string
-     *            the string to find
-     * @return the index in this String of the specified string, -1 if the
-     *         string isn't found
-     * 
+     *            the string to find.
+     * @return the index of the first character of the specified string in this
+     *         string, -1 if the specified string is not a substring.
      * @throws NullPointerException
-     *             when string is null
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *             if {@code string} is {@code null}.
      */
     public int indexOf(String string) {
         return indexOf(string, 0);
     }
 
     /**
-     * Searches in this String for the index of the specified string. The search
+     * Searches in this string for the index of the specified string. The search
      * for the string starts at the specified offset and moves towards the end
-     * of this String.
+     * of this string.
      * 
      * @param subString
-     *            the string to find
+     *            the string to find.
      * @param start
-     *            the starting offset
-     * @return the index in this String of the specified string, -1 if the
-     *         string isn't found
-     * 
+     *            the starting offset.
+     * @return the index of the first character of the specified string in this
+     *         string, -1 if the specified string is not a substring.
      * @throws NullPointerException
-     *             when string is null
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *             if {@code subString} is {@code null}.
      */
     public int indexOf(String subString, int start) {
         if (start < 0) {
@@ -1113,52 +1006,42 @@
     }
 
     /**
-     * Searches an internal table of strings for a string equal to this String.
-     * If the string is not in the table, it is added. Answers the string
-     * contained in the table which is equal to this String. The same string
-     * object is always answered for strings which are equal.
+     * Searches an internal table of strings for a string equal to this string.
+     * If the string is not in the table, it is added. Returns the string
+     * contained in the table which is equal to this string. The same string
+     * object is always returned for strings which are equal.
      * 
-     * @return the interned string equal to this String
+     * @return the interned string equal to this string.
      */
     public String intern() {
         return VM.intern(this);
     }
 
     /**
-     * Searches in this String for the last index of the specified character.
+     * Searches in this string for the last index of the specified character.
      * The search for the character starts at the end and moves towards the
-     * beginning of this String.
+     * beginning of this string.
      * 
      * @param c
-     *            the character to find
-     * @return the index in this String of the specified character, -1 if the
-     *         character isn't found
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *            the character to find.
+     * @return the index in this string of the specified character, -1 if the
+     *         character isn't found.
      */
     public int lastIndexOf(int c) {
         return lastIndexOf(c, count - 1);
     }
 
     /**
-     * Searches in this String for the index of the specified character. The
+     * Searches in this string for the index of the specified character. The
      * search for the character starts at the specified offset and moves towards
-     * the beginning of this String.
+     * the beginning of this string.
      * 
      * @param c
-     *            the character to find
+     *            the character to find.
      * @param start
-     *            the starting offset
-     * @return the index in this String of the specified character, -1 if the
-     *         character isn't found
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *            the starting offset.
+     * @return the index in this string of the specified character, -1 if the
+     *         character isn't found.
      */
     public int lastIndexOf(int c, int start) {
         if (start >= 0) {
@@ -1175,22 +1058,16 @@
     }
 
     /**
-     * Searches in this String for the last index of the specified string. The
+     * Searches in this string for the last index of the specified string. The
      * search for the string starts at the end and moves towards the beginning
-     * of this String.
+     * of this string.
      * 
      * @param string
-     *            the string to find
-     * @return the index in this String of the specified string, -1 if the
-     *         string isn't found
-     * 
+     *            the string to find.
+     * @return the index of the first character of the specified string in this
+     *         string, -1 if the specified string is not a substring.
      * @throws NullPointerException
-     *             when string is null
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *             if {@code string} is {@code null}.
      */
     public int lastIndexOf(String string) {
         // Use count instead of count - 1 so lastIndexOf("") answers count
@@ -1198,24 +1075,18 @@
     }
 
     /**
-     * Searches in this String for the index of the specified string. The search
+     * Searches in this string for the index of the specified string. The search
      * for the string starts at the specified offset and moves towards the
-     * beginning of this String.
+     * beginning of this string.
      * 
      * @param subString
-     *            the string to find
+     *            the string to find.
      * @param start
-     *            the starting offset
-     * @return the index in this String of the specified string, -1 if the
-     *         string isn't found
-     * 
+     *            the starting offset.
+     * @return the index of the first character of the specified string in this
+     *         string , -1 if the specified string is not a substring.
      * @throws NullPointerException
-     *             when string is null
-     * 
-     * @see #lastIndexOf(int)
-     * @see #lastIndexOf(int, int)
-     * @see #lastIndexOf(String)
-     * @see #lastIndexOf(String, int)
+     *             if {@code subString} is {@code null}.
      */
     public int lastIndexOf(String subString, int start) {
         int subCount = subString.count;
@@ -1250,30 +1121,30 @@
     }
 
     /**
-     * Answers the size of this String.
+     * Returns the size of this string.
      * 
-     * @return the number of characters in this String
+     * @return the number of characters in this string.
      */
     public int length() {
         return count;
     }
 
     /**
-     * Compares the specified string to this String and compares the specified
+     * Compares the specified string to this string and compares the specified
      * range of characters to determine if they are the same.
      * 
      * @param thisStart
-     *            the starting offset in this String
+     *            the starting offset in this string.
      * @param string
-     *            the string to compare
+     *            the string to compare.
      * @param start
-     *            the starting offset in string
+     *            the starting offset in the specified string.
      * @param length
-     *            the number of characters to compare
-     * @return true if the ranges of characters is equal, false otherwise
-     * 
+     *            the number of characters to compare.
+     * @return {@code true} if the ranges of characters are equal, {@code false}
+     *         otherwise
      * @throws NullPointerException
-     *             when string is null
+     *             if {@code string} is {@code null}.
      */
     public boolean regionMatches(int thisStart, String string, int start,
             int length) {
@@ -1299,24 +1170,24 @@
     }
 
     /**
-     * Compares the specified string to this String and compares the specified
+     * Compares the specified string to this string and compares the specified
      * range of characters to determine if they are the same. When ignoreCase is
      * true, the case of the characters is ignored during the comparison.
      * 
      * @param ignoreCase
-     *            specifies if case should be ignored
+     *            specifies if case should be ignored.
      * @param thisStart
-     *            the starting offset in this String
+     *            the starting offset in this string.
      * @param string
-     *            the string to compare
+     *            the string to compare.
      * @param start
-     *            the starting offset in string
+     *            the starting offset in the specified string.
      * @param length
-     *            the number of characters to compare
-     * @return true if the ranges of characters is equal, false otherwise
-     * 
+     *            the number of characters to compare.
+     * @return {@code true} if the ranges of characters are equal, {@code false}
+     *         otherwise.
      * @throws NullPointerException
-     *             when string is null
+     *             if {@code string} is {@code null}.
      */
     public boolean regionMatches(boolean ignoreCase, int thisStart,
             String string, int start, int length) {
@@ -1351,14 +1222,14 @@
     }
 
     /**
-     * Copies this String replacing occurrences of the specified character with
+     * Copies this string replacing occurrences of the specified character with
      * another character.
      * 
      * @param oldChar
-     *            the character to replace
+     *            the character to replace.
      * @param newChar
-     *            the replacement character
-     * @return a new String with occurrences of oldChar replaced by newChar
+     *            the replacement character.
+     * @return a new string with occurrences of oldChar replaced by newChar.
      */
     public String replace(char oldChar, char newChar) {
         int index = indexOf(oldChar, 0);
@@ -1375,18 +1246,17 @@
     }
     
     /**
-     * Copies this String replacing occurrences of the specified 
-     * target sequence with another sequence. 
-     * The string is processed from the beginning to the end. 
+     * Copies this string replacing occurrences of the specified target sequence
+     * with another sequence. The string is processed from the beginning to the
+     * end.
      * 
      * @param target
-     *            the sequence to replace
+     *            the sequence to replace.
      * @param replacement
-     *            the replacement sequence
-     * @return the resulting String
-     * 
-     * @throws NullPointerException if either of the arguments 
-     * is <code>null</code>
+     *            the replacement sequence.
+     * @return the resulting string.
+     * @throws NullPointerException
+     *             if {@code target} or {@code replacement} is {@code null}.
      */
     public String replace(CharSequence target, CharSequence replacement) {
         if (target == null) {
@@ -1417,50 +1287,46 @@
     }
 
     /**
-     * Compares the specified string to this String to determine if the
+     * Compares the specified string to this string to determine if the
      * specified string is a prefix.
      * 
      * @param prefix
-     *            the string to look for
-     * @return true when the specified string is a prefix of this String, false
-     *         otherwise
-     * 
+     *            the string to look for.
+     * @return {@code true} if the specified string is a prefix of this string,
+     *         {@code false} otherwise
      * @throws NullPointerException
-     *             when prefix is null
+     *             if {@code prefix} is {@code null}.
      */
     public boolean startsWith(String prefix) {
         return startsWith(prefix, 0);
     }
 
     /**
-     * Compares the specified string to this String, starting at the specified
+     * Compares the specified string to this string, starting at the specified
      * offset, to determine if the specified string is a prefix.
      * 
      * @param prefix
-     *            the string to look for
+     *            the string to look for.
      * @param start
-     *            the starting offset
-     * @return true when the specified string occurs in this String at the
-     *         specified offset, false otherwise
-     * 
+     *            the starting offset.
+     * @return {@code true} if the specified string occurs in this string at the
+     *         specified offset, {@code false} otherwise.
      * @throws NullPointerException
-     *             when prefix is null
+     *             if {@code prefix} is {@code null}.
      */
     public boolean startsWith(String prefix, int start) {
         return regionMatches(start, prefix, 0, prefix.count);
     }
 
     /**
-     * Copies a range of characters into a new String.
+     * 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
-     * 
+     *            the offset of the first character.
+     * @return a new string containing the characters from start to the end of
+     *         the string.
      * @throws IndexOutOfBoundsException
-     *             when <code>start < 0</code> or
-     *             <code>start > length()</code>
+     *             if {@code start < 0} or {@code start > length()}.
      */
     public String substring(int start) {
         if (start == 0) {
@@ -1473,17 +1339,16 @@
     }
 
     /**
-     * Copies a range of characters into a new String.
+     * Copies a range of characters into a new string.
      * 
      * @param start
-     *            the offset of the first character
+     *            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
-     * 
+     *            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>
+     *             if {@code start < 0}, {@code start > end} or {@code end >
+     *             length()}.
      */
     public String substring(int start, int end) {
         if (start == 0 && end == count) {
@@ -1498,9 +1363,9 @@
     }
 
     /**
-     * Copies the characters in this String to a character array.
+     * Copies the characters in this string to a character array.
      * 
-     * @return a character array containing the characters of this String
+     * @return a character array containing the characters of this string.
      */
     public char[] toCharArray() {
         char[] buffer = new char[count];
@@ -1509,24 +1374,24 @@
     }
 
     /**
-     * Converts the characters in this String to lowercase, using the default
+     * Converts the characters in this string to lowercase, using the default
      * Locale.
      * 
-     * @return a new String containing the lowercase characters equivalent to
-     *         the characters in this String
+     * @return a new string containing the lowercase characters equivalent to
+     *         the characters in this string.
      */
     public String toLowerCase() {
         return toLowerCase(Locale.getDefault());
     }
 
     /**
-     * Converts the characters in this String to lowercase, using the specified
+     * Converts the characters in this string to lowercase, using the specified
      * Locale.
      * 
      * @param locale
-     *            the Locale
-     * @return a new String containing the lowercase characters equivalent to
-     *         the characters in this String
+     *            the Locale to use.
+     * @return a new string containing the lowercase characters equivalent to
+     *         the characters in this string.
      */
     public String toLowerCase(Locale locale) {
         for (int o = offset, end = offset + count; o < end; o++) {
@@ -1554,10 +1419,9 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
-     * @return this String
+     * Returns this string.
+     *
+     * @return this string.
      */
     @Override
     public String toString() {
@@ -1565,11 +1429,11 @@
     }
 
     /**
-     * Converts the characters in this String to uppercase, using the default
+     * Converts the characters in this string to uppercase, using the default
      * Locale.
      * 
-     * @return a new String containing the uppercase characters equivalent to
-     *         the characters in this String
+     * @return a new string containing the uppercase characters equivalent to
+     *         the characters in this string.
      */
     public String toUpperCase() {
         return toUpperCase(Locale.getDefault());
@@ -1581,11 +1445,11 @@
      * Return the index of the specified character into the upperValues table.
      * The upperValues table contains three entries at each position. These
      * three characters are the upper case conversion. If only two characters
-     * are used, the third character in the table is &#92;u0000.
-     * 
+     * are used, the third character in the table is \u0000.
+     *
      * @param ch
      *            the char being converted to upper case
-     * 
+     *
      * @return the index into the upperValues table, or -1
      */
     private int upperIndex(int ch) {
@@ -1636,13 +1500,13 @@
     }
 
     /**
-     * Converts the characters in this String to uppercase, using the specified
+     * Converts the characters in this string to uppercase, using the specified
      * Locale.
      * 
      * @param locale
-     *            the Locale
-     * @return a new String containing the uppercase characters equivalent to
-     *         the characters in this String
+     *            the Locale to use.
+     * @return a new string containing the uppercase characters equivalent to
+     *         the characters in this string.
      */
     public String toUpperCase(Locale locale) {
         boolean turkish = "tr".equals(locale.getLanguage()); //$NON-NLS-1$
@@ -1701,16 +1565,11 @@
     }
 
     /**
-     * Answers a copy of this String with white space characters at the
-     * beginning and end removed.
-     * 
-     * If the receiver has no leading or trailing blanks then it returns itself.
-     * 
-     * Blanks are defined as characters with Unicode value
-     * <code><= &#92;u0020</code>.
+     * Copies this string removing white space characters from the beginning and
+     * end of the string.
      * 
-     * @return a new String with leading and trailing blanks removed, or this
-     *         string if there are none.
+     * @return a new string with characters <code><= \\u0020</code> removed from
+     *         the beginning and the end.
      */
     public String trim() {
         int start = offset, last = offset + count - 1;
@@ -1728,39 +1587,37 @@
     }
 
     /**
-     * Creates a new String containing the characters in the specified character
-     * array. Modifying the character array after creating the String has no
-     * effect on the String.
+     * Creates a new string containing the characters in the specified character
+     * array. Modifying the character array after creating the string has no
+     * effect on the string.
      * 
      * @param data
-     *            the array of characters
-     * @return the new String
-     * 
+     *            the array of characters.
+     * @return the new string.
      * @throws NullPointerException
-     *             when data is null
+     *             if {@code data} is {@code null}.
      */
     public static String valueOf(char[] data) {
         return new String(data, 0, data.length);
     }
 
     /**
-     * Creates a new String containing the specified characters in the character
-     * array. Modifying the character array after creating the String has no
-     * effect on the String.
+     * Creates a new string containing the specified characters in the character
+     * array. Modifying the character array after creating the string has no
+     * effect on the string.
      * 
      * @param data
-     *            the array of characters
+     *            the array of characters.
      * @param start
-     *            the starting offset in the character array
+     *            the starting offset in the character array.
      * @param length
-     *            the number of characters to use
-     * @return the new String
-     * 
+     *            the number of characters to use.
+     * @return the new string.
      * @throws IndexOutOfBoundsException
-     *             when <code>length < 0, start < 0</code> or
-     *             <code>start + length > data.length</code>
+     *             if {@code length < 0}, {@code start < 0} or {@code start +
+     *             length > data.length}
      * @throws NullPointerException
-     *             when data is null
+     *             if {@code data} is {@code null}.
      */
     public static String valueOf(char[] data, int start, int length) {
         return new String(data, start, length);
@@ -1770,8 +1627,8 @@
      * Converts the specified character to its string representation.
      * 
      * @param value
-     *            the character
-     * @return the character converted to a string
+     *            the character.
+     * @return the character converted to a string.
      */
     public static String valueOf(char value) {
         String s;
@@ -1788,8 +1645,8 @@
      * Converts the specified double to its string representation.
      * 
      * @param value
-     *            the double
-     * @return the double converted to a string
+     *            the double.
+     * @return the double converted to a string.
      */
     public static String valueOf(double value) {
         return Double.toString(value);
@@ -1799,8 +1656,8 @@
      * Converts the specified float to its string representation.
      * 
      * @param value
-     *            the float
-     * @return the float converted to a string
+     *            the float.
+     * @return the float converted to a string.
      */
     public static String valueOf(float value) {
         return Float.toString(value);
@@ -1810,8 +1667,8 @@
      * Converts the specified integer to its string representation.
      * 
      * @param value
-     *            the integer
-     * @return the integer converted to a string
+     *            the integer.
+     * @return the integer converted to a string.
      */
     public static String valueOf(int value) {
         return Integer.toString(value);
@@ -1821,8 +1678,8 @@
      * Converts the specified long to its string representation.
      * 
      * @param value
-     *            the long
-     * @return the long converted to a string
+     *            the long.
+     * @return the long converted to a string.
      */
     public static String valueOf(long value) {
         return Long.toString(value);
@@ -1830,12 +1687,12 @@
 
     /**
      * Converts the specified object to its string representation. If the object
-     * is null answer the string <code>"null"</code>, otherwise use
-     * <code>toString()</code> to get the string representation.
+     * is null return the string {@code "null"}, otherwise use {@code
+     * toString()} to get the string representation.
      * 
      * @param value
-     *            the object
-     * @return the object converted to a string
+     *            the object.
+     * @return the object converted to a string, or the string {@code "null"}.
      */
     public static String valueOf(Object value) {
         return value != null ? value.toString() : "null"; //$NON-NLS-1$
@@ -1843,29 +1700,28 @@
 
     /**
      * Converts the specified boolean to its string representation. When the
-     * boolean is true answer <code>"true"</code>, otherwise answer
-     * <code>"false"</code>.
+     * boolean is {@code true} return {@code "true"}, otherwise return {@code
+     * "false"}.
      * 
      * @param value
-     *            the boolean
-     * @return the boolean converted to a string
+     *            the boolean.
+     * @return the boolean converted to a string.
      */
     public static String valueOf(boolean value) {
         return value ? "true" : "false"; //$NON-NLS-1$ //$NON-NLS-2$
     }
 
     /**
-     * Answers whether the characters in the StringBuffer strbuf are the same as
-     * those in this String.
+     * Returns whether the characters in the StringBuffer {@code strbuf} are the
+     * same as those in this string.
      * 
      * @param strbuf
-     *            the StringBuffer to compare this String to
-     * @return true when the characters in strbuf are identical to those in this
-     *         String. If they are not, false will be returned.
-     * 
+     *            the StringBuffer to compare this string to.
+     * @return {@code true} if the characters in {@code strbuf} are identical to
+     *         those in this string. If they are not, {@code false} will be
+     *         returned.
      * @throws NullPointerException
-     *             when strbuf is null
-     * 
+     *             if {@code strbuf} is {@code null}.
      * @since 1.4
      */
     public boolean contentEquals(StringBuffer strbuf) {
@@ -1880,14 +1736,12 @@
     }
 
     /**
-     * <p>
-     * Compares a <code>CharSequence</code> to this <code>String</code> to
-     * determine if their contents are equal.
-     * </p>
-     * 
+     * Compares a {@code CharSequence} to this {@code String} to determine if
+     * their contents are equal.
+     *
      * @param cs
-     *            The character sequence to compare to.
-     * @return <code>true</code> if equal, otherwise <code>false</code>
+     *            the character sequence to compare to.
+     * @return {@code true} if equal, otherwise {@code false}
      * @since 1.5
      */
     public boolean contentEquals(CharSequence cs) {
@@ -1909,17 +1763,16 @@
     }
 
     /**
-     * Determines whether a this String matches a given regular expression.
+     * Determines whether this string matches a given regular expression.
      * 
      * @param expr
-     *            the regular expression to be matched
-     * @return true if the expression matches, otherwise false
-     * 
+     *            the regular expression to be matched.
+     * @return {@code true} if the expression matches, otherwise {@code false}.
      * @throws PatternSyntaxException
-     *             if the syntax of the supplied regular expression is not valid
+     *             if the syntax of the supplied regular expression is not
+     *             valid.
      * @throws NullPointerException
-     *             if expr is null
-     * 
+     *             if {@code expr} is {@code null}.
      * @since 1.4
      */
     public boolean matches(String expr) {
@@ -1927,18 +1780,18 @@
     }
 
     /**
-     * Replace any substrings within this String that match the supplied regular
-     * expression expr, with the String substitute.
+     * Replace any substrings within this string that match the supplied regular
+     * expression {@code expr}, with the string {@code substitute}.
      * 
      * @param expr
-     *            the regular expression to match
+     *            the regular expression to match.
      * @param substitute
-     *            the string to replace the matching substring with
-     * @return the new string
-     * 
-     * @throws NullPointerException
-     *             if expr is null
-     * 
+     *            the string to replace the matching substring with.
+     * @return the new string.
+     * @throws PatternSyntaxException
+     *             if the syntax of the supplied regular expression is not
+     *             valid.
+     * @see Pattern
      * @since 1.4
      */
     public String replaceAll(String expr, String substitute) {
@@ -1946,18 +1799,20 @@
     }
 
     /**
-     * Replace any substrings within this String that match the supplied regular
-     * expression expr, with the String substitute.
+     * Replace the first substring within this string that matches the supplied
+     * regular expression {@code expr}, with the string {@code substitute}.
      * 
      * @param expr
-     *            the regular expression to match
+     *            the regular expression to match.
      * @param substitute
-     *            the string to replace the matching substring with
-     * @return the new string
-     * 
+     *            the string to replace the matching substring with.
+     * @return the new string.
+     * @throws PatternSyntaxException
+     *             if the syntax of the supplied regular expression is not
+     *             valid.
      * @throws NullPointerException
-     *             if expr is null
-     * 
+     *             if {@code strbuf} is {@code null}.
+     * @see Pattern
      * @since 1.4
      */
     public String replaceFirst(String expr, String substitute) {
@@ -1965,16 +1820,18 @@
     }
 
     /**
-     * Replace any substrings within this String that match the supplied regular
-     * expression expr, with the String substitute.
+     * Splits this string using the supplied regular expression {@code expr}.
      * 
      * @param expr
-     *            the regular expression to match
-     * @return the new string
-     * 
+     *            the regular expression used to divide the string.
+     * @return an array of Strings created by separating the string along
+     *         matches of the regular expression.
      * @throws NullPointerException
-     *             if expr is null
-     * 
+     *             if {@code expr} is {@code null}.
+     * @throws PatternSyntaxException
+     *             if the syntax of the supplied regular expression is not
+     *             valid.
+     * @see Pattern
      * @since 1.4
      */
     public String[] split(String expr) {
@@ -1982,19 +1839,22 @@
     }
 
     /**
-     * Splits this String using the supplied regular expression expr. max
-     * controls the number of times that the pattern is applied to the string.
+     * Splits this string using the supplied regular expression {@code expr}.
+     * The parameter {@code max} controls the behavior how many times the
+     * pattern is applied to the string.
      * 
      * @param expr
-     *            the regular expression used to divide the string
+     *            the regular expression used to divide the string.
      * @param max
-     *            the number of times to apply the pattern
+     *            the number of entries in the resulting array.
      * @return an array of Strings created by separating the string along
      *         matches of the regular expression.
-     * 
      * @throws NullPointerException
-     *             if expr is null
-     * 
+     *             if {@code expr} is {@code null}.
+     * @throws PatternSyntaxException
+     *             if the syntax of the supplied regular expression is not
+     *             valid.
+     * @see Pattern#split(CharSequence, int)
      * @since 1.4
      */
     public String[] split(String expr, int max) {
@@ -2003,21 +1863,17 @@
 
     /**
      * Has the same result as the substring function, but is present so that
-     * String may implement the CharSequence interface.
+     * string may implement the CharSequence interface.
      * 
      * @param start
-     *            the offset the first character
+     *            the offset the first character.
      * @param end
-     *            the offset of one past the last character to include
-     * 
-     * @return the subsequence requested
-     * 
+     *            the offset of one past the last character to include.
+     * @return the subsequence requested.
      * @throws IndexOutOfBoundsException
-     *             when start or end is less than zero, start is greater than
-     *             end, or end is greater than the length of the String.
-     * 
+     *             if {@code start < 0}, {@code end < 0}, {@code start > end} or
+     *             {@code end > length()}.
      * @see java.lang.CharSequence#subSequence(int, int)
-     * 
      * @since 1.4
      */
     public CharSequence subSequence(int start, int end) {
@@ -2025,18 +1881,15 @@
     }
 
     /**
-     * <p>
-     * Retrieves the Unicode code point value at the <code>index</code>.
-     * </p>
+     * Retrieves the Unicode code point (character) value at the specified
+     * {@code index}.
      * 
      * @param index
-     *            The index to the <code>char</code> code unit within this
-     *            object.
-     * @return The Unicode code point value.
+     *            the index to the {@code char} code unit within this string.
+     * @return the Unicode code point value.
      * @throws IndexOutOfBoundsException
-     *             if <code>index</code> is negative or greater than or equal
-     *             to {@link #length()}.
-     * @see Character
+     *             if {@code index} is negative or greater than or equal to
+     *             {@code length()}.
      * @see Character#codePointAt(char[], int, int)
      * @since 1.5
      */
@@ -2049,19 +1902,15 @@
     }
 
     /**
-     * <p>
-     * Retrieves the Unicode code point value that precedes the
-     * <code>index</code>.
-     * </p>
+     * Retrieves the Unicode code point value that precedes the specified
+     * {@code index}.
      * 
      * @param index
-     *            The index to the <code>char</code> code unit within this
-     *            object.
-     * @return The Unicode code point value.
+     *            the index to the {@code char} code unit within this string.
+     * @return the Unicode code point value.
      * @throws IndexOutOfBoundsException
-     *             if <code>index</code> is less than 1 or greater than
-     *             {@link #length()}.
-     * @see Character
+     *             if {@code index} is less than 1 or greater than
+     *             {@code length()}.
      * @see Character#codePointBefore(char[], int, int)
      * @since 1.5
      */
@@ -2074,20 +1923,19 @@
     }
 
     /**
-     * <p>
-     * Calculates the number of Unicode code points between
-     * <code>beginIndex</code> and <code>endIndex</code>.
-     * </p>
+     * Calculates the number of Unicode code points between {@code beginIndex}
+     * and {@code endIndex}.
      * 
      * @param beginIndex
-     *            The inclusive beginning index of the subsequence.
+     *            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.
+     *            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()}.
+     *             if {@code beginIndex} is negative or greater than {@code
+     *             endIndex} or {@code endIndex} is greater than {@code
+     *             length()}.
+     * @see Character#codePointCount(CharSequence, int, int)
      * @since 1.5
      */
     public int codePointCount(int beginIndex, int endIndex) {
@@ -2099,15 +1947,13 @@
     }
 
     /**
-     * <p>
-     * Determines if this <code>String</code> contains the sequence of
-     * characters in the <code>CharSequence</code> passed.
-     * </p>
-     * 
+     * Determines if this {@code String} contains the sequence of characters in
+     * the {@code CharSequence} passed.
+     *
      * @param cs
-     *            The character sequence to search for.
-     * @return <code>true</code> if the sequence of characters are contained
-     *         in this object; otherwise <code>false</code>
+     *            the character sequence to search for.
+     * @return {@code true} if the sequence of characters are contained in this
+     *         string, otherwise {@code false}.
      * @since 1.5
      */
     public boolean contains(CharSequence cs) {
@@ -2118,21 +1964,18 @@
     }
 
     /**
-     * <p>
-     * Returns the index within this object that is offset from
-     * <code>index</code> by <code>codePointOffset</code> code points.
-     * </p>
-     * 
+     * Returns the index within this object that is offset from {@code index} by
+     * {@code codePointOffset} code points.
+     *
      * @param index
-     *            The index within this object to calculate the offset from.
+     *            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.
+     *            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>.
+     *             if {@code index} is negative or greater than {@code length()}
+     *             or if there aren't enough code points before or after {@code
+     *             index} to match {@code codePointOffset}.
      * @since 1.5
      */
     public int offsetByCodePoints(int index, int codePointOffset) {
@@ -2143,44 +1986,49 @@
     }
 
     /**
-     * Returns a printf-style formatted string, using the supplied format and
-     * arguments. This function is a shortcut to
-     * <code>format(Locale.getDefault(), format, args)</code>.
+     * Returns a formatted string, using the supplied format and arguments,
+     * using the default locale.
      * 
      * @param format
-     *            a format string
+     *            a format string.
      * @param args
-     *            arguments to replace format specifiers, may be none
+     *            arguments to replace format specifiers (may be none).
+     * @return the formatted string.
      * @throws NullPointerException
-     *             if the format is null
-     * @throws IllegalArgumentException
-     *             if the format is invalid
-     * @return The formatted string
-     * @since 1.5
+     *             if {@code format} is {@code null}.
+     * @throws java.util.IllegalFormatException
+     *             if the format is invalid.
      * @see java.util.Formatter
+     * @since 1.5
      */
     public static String format(String format, Object... args) {
         return format(Locale.getDefault(), format, args);
     }
 
     /**
-     * Returns a printf-style formatted string, using the supplied format and
-     * arguments, accordingly to the specified locale.
-     * 
+     * Returns a formatted string, using the supplied format and arguments,
+     * accordingly to the specified locale.
+     * <p>
+     * Note that this is a convenience method. Using it involves creating an
+     * internal {@link java.util.Formatter} instance on-the-fly, which is
+     * somewhat costly in terms of memory and time. This is probably acceptable
+     * if you use the method only rarely, but if you rely on it for formatting a
+     * large number of strings, consider creating and reusing your own
+     * {@link java.util.Formatter} instance instead.
+     *
      * @param loc
-     *            the locale to apply; <code>null</code> value means no
-     *            localization
+     *            the locale to apply; {@code null} value means no localization.
      * @param format
-     *            a format string
+     *            a format string.
      * @param args
-     *            arguments to replace format specifiers, may be none
+     *            arguments to replace format specifiers (may be none).
+     * @return the formatted string.
      * @throws NullPointerException
-     *             if the format is null
-     * @throws IllegalArgumentException
-     *             if the format is invalid
-     * @return The formatted string
-     * @since 1.5
+     *             if {@code format} is {@code null}.
+     * @throws java.util.IllegalFormatException
+     *             if the format is invalid.
      * @see java.util.Formatter
+     * @since 1.5
      */
     public static String format(Locale loc, String format, Object... args) {
         if (format == null) {
@@ -2196,7 +2044,7 @@
      * An implementation of a String.indexOf that is supposed to perform
      * substantially better than the default algorithm if the "needle" (the
      * subString being searched for) is a constant string.
-     * 
+     *
      * For example, a JIT, upon encoutering a call to String.indexOf(String),
      * where the needle is a constant string, may compute the values cache, md2
      * and lastChar, and change the call to the following method.
@@ -2237,7 +2085,7 @@
     }
 
     /*
-     * Returns the character array for this String.
+     * Returns the character array for this string.
      */
     char[] getValue() {
         return value;