harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772552 [2/5] - /harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/
Date Thu, 07 May 2009 08:42:03 GMT
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ChoiceFormat.java Thu May  7 08:42:00 2009
@@ -23,11 +23,50 @@
 import java.util.Locale;
 
 /**
- * ChoiceFormat is used to associate strings with ranges of double values. The
- * strings and ranges are either specified using arrays or with a pattern which
- * is parsed to determine the Strings and ranges.
+ * Returns a fixed string based on a numeric value. The class can be used in
+ * conjunction with the {@link MessageFormat} class to handle plurals in
+ * messages. {@code ChoiceFormat} enables users to attach a format to a range of
+ * numbers. The choice is specified with an ascending list of doubles, where
+ * each item specifies a half-open interval up to the next item as in the
+ * following: X matches j if and only if {@code limit[j] <= X < limit[j+1]}.
+ * <p>
+ * If there is no match, then either the first or last index is used. The first
+ * or last index is used depending on whether the number is too low or too high.
+ * The length of the format array must be the same as the length of the limits
+ * array.
+ * <h5>Examples:</h5>
+ * <blockquote>
+ *
+ * <pre>
+ * double[] limits = {1, 2, 3, 4, 5, 6, 7};
+ * String[] fmts = {"Sun", "Mon", "Tue", "Wed", "Thur", "Fri", "Sat"};
+ *
+ * double[] limits2 = {0, 1, ChoiceFormat.nextDouble(1)};
+ * String[] fmts2 = {"no files", "one file", "many files"};
+ * </pre>
+ * </blockquote>
+ * <p>
+ * ChoiceFormat.nextDouble(double) allows to get the double following the one
+ * passed to the method. This is used to create half open intervals.
+ * <p>
+ * {@code ChoiceFormat} objects also may be converted to and from patterns.
+ * The conversion can be done programmatically, as in the example above, or
+ * by using a pattern like the following:
+ * <blockquote>
+ *
+ * <pre>
+ * "1#Sun|2#Mon|3#Tue|4#Wed|5#Thur|6#Fri|7#Sat"
+ * "0#are no files|1#is one file|1&lt;are many files"
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * where:
+ * <ul>
+ * <li><number>"#"</number> specifies an inclusive limit value;</li>
+ * <li><number>"<"</number> specifies an exclusive limit value.</li>
+ * </ul>
  */
-
 public class ChoiceFormat extends NumberFormat {
 
     private static final long serialVersionUID = 1795184449645032964L;
@@ -37,31 +76,35 @@
     private String[] choiceFormats;
 
     /**
-     * Constructs a new ChoiceFormat with the specified ranges and associated
-     * strings.
-     * 
+     * Constructs a new {@code ChoiceFormat} with the specified double values
+     * and associated strings. When calling
+     * {@link #format(double, StringBuffer, FieldPosition) format} with a double
+     * value {@code d}, then the element {@code i} in {@code formats} is
+     * selected where {@code i} fulfills {@code limits[i] <= d < limits[i+1]}.
+     * <p>
+     * The length of the {@code limits} and {@code formats} arrays must be the
+     * same.
+     *
      * @param limits
-     *            an array of double, the ranges are greater or equal to the
-     *            value in lower index up to less than the value in the next
-     *            higher index. The bounds of the lowest and highest indexes are
-     *            negative and positive infinity.
+     *            an array of doubles in ascending order. The lowest and highest
+     *            possible values are negative and positive infinity.
      * @param formats
-     *            the strings associated with the ranges. The lower bound of the
-     *            associated range is at the same index as the string.
+     *            the strings associated with the ranges defined through {@code
+     *            limits}. The lower bound of the associated range is at the
+     *            same index as the string.
      */
     public ChoiceFormat(double[] limits, String[] formats) {
         setChoices(limits, formats);
     }
 
     /**
-     * Constructs a new ChoiceFormat with the strings and ranges parsed from the
-     * specified pattern.
+     * Constructs a new {@code ChoiceFormat} with the strings and limits parsed
+     * from the specified pattern.
      * 
      * @param template
-     *            the pattern of strings and ranges
-     * 
-     * @exception IllegalArgumentException
-     *                then an error occurs parsing the pattern
+     *            the pattern of strings and ranges.
+     * @throws IllegalArgumentException
+     *            if an error occurs while parsing the pattern.
      */
     public ChoiceFormat(String template) {
         applyPattern(template);
@@ -69,13 +112,12 @@
 
     /**
      * Parses the pattern to determine new strings and ranges for this
-     * ChoiceFormat.
+     * {@code ChoiceFormat}.
      * 
      * @param template
-     *            the pattern of strings and ranges
-     * 
-     * @exception IllegalArgumentException
-     *                then an error occurs parsing the pattern
+     *            the pattern of strings and ranges.
+     * @throws IllegalArgumentException
+     *            if an error occurs while parsing the pattern.
      */
     public void applyPattern(String template) {
         double[] limits = new double[5];
@@ -140,10 +182,10 @@
     }
 
     /**
-     * Answers a new instance of ChoiceFormat with the same ranges and strings
-     * as this ChoiceFormat.
+     * Returns a new instance of {@code ChoiceFormat} with the same ranges and
+     * strings as this {@code ChoiceFormat}.
      * 
-     * @return a shallow copy of this ChoiceFormat
+     * @return a shallow copy of this {@code ChoiceFormat}.
      * 
      * @see java.lang.Cloneable
      */
@@ -156,15 +198,14 @@
     }
 
     /**
-     * Compares the specified object to this ChoiceFormat and answer if they are
-     * equal. The object must be an instance of ChoiceFormat and have the same
-     * limits and formats.
+     * Compares the specified object with this {@code ChoiceFormat}. The object
+     * must be an instance of {@code ChoiceFormat} and have the same limits and
+     * formats to be equal to this instance.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this ChoiceFormat, false
-     *         otherwise
-     * 
+     *            the object to compare with this instance.
+     * @return {@code true} if the specified object is equal to this instance;
+     *         {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -181,16 +222,16 @@
     }
 
     /**
-     * Appends to the specified StringBuffer the string associated with the
-     * range in which the specified double value fits.
+     * Appends the string associated with the range in which the specified
+     * double value fits to the specified string buffer.
      * 
      * @param value
-     *            the double to format
+     *            the double to format.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted value to.
      * @param field
-     *            a FieldPosition which is ignored
-     * @return the StringBuffer parameter <code>buffer</code>
+     *            a {@code FieldPosition} which is ignored.
+     * @return the string buffer.
      */
     @Override
     public StringBuffer format(double value, StringBuffer buffer,
@@ -205,16 +246,16 @@
     }
 
     /**
-     * Appends to the specified StringBuffer the string associated with the
-     * range in which the specified long value fits.
+     * Appends the string associated with the range in which the specified long
+     * value fits to the specified string buffer.
      * 
      * @param value
-     *            the long to format
+     *            the long to format.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted value to.
      * @param field
-     *            a FieldPosition which is ignored
-     * @return the StringBuffer parameter <code>buffer</code>
+     *            a {@code FieldPosition} which is ignored.
+     * @return the string buffer.
      */
     @Override
     public StringBuffer format(long value, StringBuffer buffer,
@@ -223,31 +264,30 @@
     }
 
     /**
-     * Answers the Strings associated with the ranges of this ChoiceFormat.
+     * Returns the strings associated with the ranges of this {@code
+     * ChoiceFormat}.
      * 
-     * @return an array of String
+     * @return an array of format strings.
      */
     public Object[] getFormats() {
         return choiceFormats;
     }
 
     /**
-     * Answers the ranges of this ChoiceFormat.
+     * Returns the limits of this {@code ChoiceFormat}.
      * 
-     * @return an array of double, the ranges are greater or equal to the value
-     *         in lower index up to less than the value in the next higher
-     *         index. The bounds of the lowest and highest indexes are negative
-     *         and positive infinity.
+     * @return the array of doubles which make up the limits of this {@code
+     *         ChoiceFormat}.
      */
     public double[] getLimits() {
         return choiceLimits;
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
+     * Returns an integer hash code for the receiver. Objects which are equal
+     * return the same value for this method.
      * 
-     * @return the receiver's hash
+     * @return the receiver's hash.
      * 
      * @see #equals
      */
@@ -262,12 +302,12 @@
     }
 
     /**
-     * Answers the double value which is closest to the specified double but
+     * Returns the double value which is closest to the specified double but
      * larger.
      * 
      * @param value
-     *            a double value
-     * @return the next larger double value
+     *            a double value.
+     * @return the next larger double value.
      */
     public static final double nextDouble(double value) {
         if (value == Double.POSITIVE_INFINITY) {
@@ -284,32 +324,49 @@
     }
 
     /**
-     * Answers the double value which is closest to the specified double but
+     * Returns the double value which is closest to the specified double but
      * either larger or smaller as specified.
      * 
      * @param value
-     *            a double value
+     *            a double value.
      * @param increment
-     *            true to get a larger value, false to get a smaller value
-     * @return the next larger or smaller double value
+     *            {@code true} to get the next larger value, {@code false} to
+     *            get the previous smaller value.
+     * @return the next larger or smaller double value.
      */
     public static double nextDouble(double value, boolean increment) {
         return increment ? nextDouble(value) : previousDouble(value);
     }
 
     /**
-     * Parse a Double from the specified String starting at the index specified
-     * by the ParsePosition. The String is compared to the strings of this
-     * ChoiceFormat and if a match occurs, the answer is the lower bound of the
-     * corresponding range. If the string is successfully parsed, the index of
-     * the ParsePosition is updated to the index following the parsed text.
-     * 
+     * Parses a double from the specified string starting at the index specified
+     * by {@code position}. The string is compared to the strings of this
+     * {@code ChoiceFormat} and if a match occurs then the lower bound of the
+     * corresponding range in the limits array is returned. If the string is
+     * successfully parsed then the index of the {@code ParsePosition} passed to
+     * this method is updated to the index following the parsed text.
+     * <p>
+     * If one of the format strings of this {@code ChoiceFormat} instance is
+     * found in {@code string} starting at {@code position.getIndex()} then
+     * <ul>
+     * <li>the index in {@code position} is set to the index following the
+     * parsed text;
+     * <li>the {@link java.lang.Double Double} corresponding to the format
+     * string is returned.</li>
+     * </ul>
+     * <p>
+     * If none of the format strings is found in {@code string} then
+     * <ul>
+     * <li>the error index in {@code position} is set to the current index in
+     * {@code position};</li>
+     * <li> {@link java.lang.Double#NaN Double.NaN} is returned.
+     * </ul>
      * @param string
-     *            the String to parse
+     *            the source string to parse.
      * @param position
-     *            the ParsePosition, updated on return with the index following
-     *            the parsed text, or on error the index is unchanged and the
-     *            error index is set to the index where the error occurred
+     *            input/output parameter, specifies the start index in {@code
+     *            string} from where to start parsing. See the <em>Returns</em>
+     *            section for a description of the output values.
      * @return a Double resulting from the parse, or Double.NaN if there is an
      *         error
      */
@@ -327,12 +384,12 @@
     }
 
     /**
-     * Answers the double value which is closest to the specified double but
+     * Returns the double value which is closest to the specified double but
      * smaller.
      * 
      * @param value
-     *            a double value
-     * @return the next smaller double value
+     *            a double value.
+     * @return the next smaller double value.
      */
     public static final double previousDouble(double value) {
         if (value == Double.NEGATIVE_INFINITY) {
@@ -349,16 +406,22 @@
     }
 
     /**
-     * Sets the ranges and associated strings of this ChoiceFormat.
-     * 
+     * Sets the double values and associated strings of this ChoiceFormat. When
+     * calling {@link #format(double, StringBuffer, FieldPosition) format} with
+     * a double value {@code d}, then the element {@code i} in {@code formats}
+     * is selected where {@code i} fulfills
+     * {@code limits[i] <= d < limits[i+1]}.
+     * <p>
+     * The length of the {@code limits} and {@code formats} arrays must be the
+     * same.
+     *
      * @param limits
-     *            an array of double, the ranges are greater or equal to the
-     *            value in lower index up to less than the value in the next
-     *            higher index. The bounds of the lowest and highest indexes are
-     *            negative and positive infinity.
+     *            an array of doubles in ascending order. The lowest and highest
+     *            possible values are negative and positive infinity.
      * @param formats
-     *            the strings associated with the ranges. The lower bound of the
-     *            range is at the same index as the string.
+     *            the strings associated with the ranges defined through {@code
+     *            limits}. The lower bound of the associated range is at the
+     *            same index as the string.
      */
     public void setChoices(double[] limits, String[] formats) {
         if (limits.length != formats.length) {
@@ -377,10 +440,10 @@
     }
 
     /**
-     * Answers the pattern of this ChoiceFormat which specified the ranges and
-     * their associated strings.
+     * Returns the pattern of this {@code ChoiceFormat} which specifies the
+     * ranges and their associated strings.
      * 
-     * @return the pattern
+     * @return the pattern.
      */
     public String toPattern() {
         StringBuffer buffer = new StringBuffer();

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationElementIterator.java Thu May  7 08:42:00 2009
@@ -18,62 +18,35 @@
 package java.text;
 
 /**
- * <p>
- * <code>CollationElementIterator</code> is created by a
- * <code>RuleBasedCollator</code> to iterate through a string. The return
+ * Created by a {@code RuleBasedCollator} to iterate through a string. The
  * result of each iteration is a 32-bit collation element that defines the
  * ordering priority of the next character or sequence of characters in the
  * source string.
- * </p>
  * <p>
  * For illustration, consider the following in Spanish:
- * </p>
- * 
  * <p>
- * <code>
- * "ca" -> the first collation element is collation_element('c') and second
+ * "ca": the first collation element is collation_element('c') and second
  * collation element is collation_element('a').
- * </code>
- * </p>
- * 
- * <p>
- * <code>
- * Since "ch" in Spanish sorts as one entity, the below example returns one
- * collation element for the two characters 'c' and 'h'
- * </code>
- * </p>
- * 
  * <p>
- * <code>
- * "cha" -> the first collation element is collation_element('ch') and second
- * collation element is collation_element('a').
- * </code>
- * </p>
+ * Since "ch" in Spanish sorts as one entity, the example below returns one
+ * collation element for the two characters 'c' and 'h':
+ * <p>
+ * "cha": the first collation element is collation_element('ch') and the second
+ * one is collation_element('a').
+ * <p>
+ * In German, since the character '&#92;u0086' is a composed character of 'a'
+ * and 'e', the iterator returns two collation elements for the single character
+ * '&#92;u0086':
  * <p>
- * And in German,
- * </p>
- * 
- * <p>
- * <code>
- * Since the character '&#92;u0086' is a composed character of 'a' and 'e', the iterator
- * returns two collation elements for the single character '&#92;u0086'
- * </code>
- * </p>
- * <p>
- * <code>
- * "&#92;u0086b" -> the first
- * collation element is collation_element('a'), the second collation element is
- * collation_element('e'), and the third collation element is
+ * "&#92;u0086b": the first collation element is collation_element('a'), the
+ * second one is collation_element('e'), and the third collation element is
  * collation_element('b').
- * </code>
- * </p>
- * 
  */
 public final class CollationElementIterator {
 
     /**
      * This constant is returned by the iterator in the methods
-     * <code>next()</code> and <code>previous()</code> when the end or the
+     * {@code next()} and {@code previous()} when the end or the
      * beginning of the source string has been reached, and there are no more
      * valid collation elements to return.
      */
@@ -87,8 +60,8 @@
 
     /**
      * Obtains the maximum length of any expansion sequence that ends with the
-     * specified collation element. If there is no expansion with this collation
-     * element as the last element, returns <code>1</code>.
+     * specified collation element. Returns {@code 1} if there is no expansion
+     * with this collation element as the last element.
      * 
      * @param order
      *            a collation element that has been previously obtained from a
@@ -103,23 +76,25 @@
 
     /**
      * Obtains the character offset in the source string corresponding to the
-     * next collation element. This value could be any of: <ui>
+     * next collation element. This value could be any of:
+     * <ul>
      * <li>The index of the first character in the source string that matches
-     * the value of the next collation element. (This means that if
-     * setOffset(offset) sets the index in the middle of a contraction,
-     * getOffset() returns the index of the first character in the contraction,
-     * which may not be equal to the original offset that was set. Hence calling
-     * getOffset() immediately after setOffset(offset) does not guarantee that
-     * the original offset set will be returned.)</li>
+     * the value of the next collation element. This means that if
+     * {@code setOffset(offset)} sets the index in the middle of a contraction,
+     * {@code getOffset()} returns the index of the first character in the
+     * contraction, which may not be equal to the original offset that was set.
+     * Hence calling {@code getOffset()} immediately after
+     * {@code setOffset(offset)} does not guarantee that the original offset set
+     * will be returned.</li>
      * <li>If normalization is on, the index of the immediate subsequent
      * character, or composite character with the first character, having a
      * combining class of 0.</li>
      * <li>The length of the source string, if iteration has reached the end.
      * </li>
-     * <ui>
+     * </ul>
      * 
      * @return The position of the collation element in the source string that
-     *         will be returned in the next invocation of the {@link #next()}
+     *         will be returned by the next invocation of the {@link #next()}
      *         method.
      */
     public int getOffset() {
@@ -129,7 +104,7 @@
     /**
      * Obtains the next collation element in the source string.
      * 
-     * @return the next collation element or <code>NULLORDER</code> if the end
+     * @return the next collation element or {@code NULLORDER} if the end
      *         of the iteration has been reached.
      */
     public int next() {
@@ -139,7 +114,7 @@
     /**
      * Obtains the previous collation element in the source string.
      * 
-     * @return the previous collation element, or <code>NULLORDER</code> when
+     * @return the previous collation element, or {@code NULLORDER} when
      *         the start of the iteration has been reached.
      */
     public int previous() {
@@ -151,7 +126,8 @@
      * first 16 bits. This value is unsigned.
      * 
      * @param order
-     * @return the element's 16 bits primary order.
+     *            the element of the collation.
+     * @return the element's 16 bit primary order.
      */
     public static final int primaryOrder(int order) {
         return com.ibm.icu.text.CollationElementIterator.primaryOrder(order);
@@ -159,14 +135,12 @@
 
     /**
      * Repositions the cursor to point at the first element of the current
-     * string. The next call to <code>next()</code> or <code>previous()</code>
-     * will return the first and last collation element in the string,
-     * respectively.
+     * string. The next call to {@link #next()} or {@link #previous()} will
+     * return the first and last collation element in the string, respectively.
      * <p>
-     * If the <code>RuleBasedCollator</code> used by this iterator has had its
-     * attributes changed, calling <code>reset()</code> will reinitialize the
-     * iterator to use the new attributes.
-     * </p>
+     * If the {@code RuleBasedCollator} used by this iterator has had its
+     * attributes changed, calling {@code reset()} reinitializes the iterator to
+     * use the new attributes.
      */
     public void reset() {
         this.icuIterator.reset();
@@ -177,7 +151,8 @@
      * 16th to 23th bits, inclusive. This value is unsigned.
      * 
      * @param order
-     * @return the 8 bit secondary order of the element
+     *            the element of the collator.
+     * @return the 8 bit secondary order of the element.
      */
     public static final short secondaryOrder(int order) {
         return (short) com.ibm.icu.text.CollationElementIterator
@@ -190,18 +165,16 @@
      * After this call completes, an invocation of the {@link #next()} method
      * will return this collation element.
      * <p>
-     * If <code>newOffset</code> corresponds to a character which is part of a
-     * sequence that maps to a single collation element the iterator is adjusted
-     * to the start of that sequence. As a result of this, any subsequent call
-     * made to <code>getOffset()</code> may not return the same value set by
-     * this method.
-     * </p>
+     * If {@code newOffset} corresponds to a character which is part of a
+     * sequence that maps to a single collation element then the iterator is
+     * adjusted to the start of that sequence. As a result of this, any
+     * subsequent call made to {@code getOffset()} may not return the same value
+     * set by this method.
      * <p>
      * If the decomposition mode is on, and offset is in the middle of a
      * decomposable range of source text, the iterator may not return a correct
      * result for the next forwards or backwards iteration. The user must ensure
      * that the offset is not in the middle of a decomposable range.
-     * </p>
      * 
      * @param newOffset
      *            the character offset into the original source string to set.
@@ -213,7 +186,7 @@
     }
 
     /**
-     * Sets a new source string iterator for iteration, and reset the offset to
+     * Sets a new source string iterator for iteration, and resets the offset to
      * the beginning of the text.
      * 
      * @param source
@@ -224,11 +197,11 @@
     }
 
     /**
-     * Sets a new source string for iteration, and reset the offset to the
+     * Sets a new source string for iteration, and resets the offset to the
      * beginning of the text.
      * 
      * @param source
-     *            the new source string for iteration
+     *            the new source string for iteration.
      */
     public void setText(String source) {
         this.icuIterator.setText(source);
@@ -239,7 +212,8 @@
      * last 8 bits. This value is unsigned.
      * 
      * @param order
-     * @return the 8 bits tertiary order of the element
+     *            the element of the collation.
+     * @return the 8 bit tertiary order of the element.
      */
     public static final short tertiaryOrder(int order) {
         return (short) com.ibm.icu.text.CollationElementIterator

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/CollationKey.java Thu May  7 08:42:00 2009
@@ -18,10 +18,65 @@
 package java.text;
 
 /**
- * CollationKey represents the collation order of a particular String for a
- * specific Collator. CollationKeys can be compared to determine the relative
- * ordering of their source Strings. This is useful when the Strings must be
- * compared multiple times, as in sorting.
+ * Represents a string under the rules of a specific {@code Collator} object.
+ * Comparing two {@code CollationKey} instances returns the relative order of
+ * the strings they represent.
+ * <p>
+ * Since the rule set of collators can differ, the sort orders of the same
+ * string under two different {@code Collator} instances might differ. Hence
+ * comparing collation keys generated from different {@code Collator} instances
+ * can give incorrect results.
+ * <p>
+ * Both the method {@code CollationKey.compareTo(CollationKey)} and the method
+ * {@code Collator.compare(String, String)} compares two strings and returns
+ * their relative order. The performance characteristics of these two approaches
+ * can differ.
+ * <p>
+ * During the construction of a {@code CollationKey}, the entire source string
+ * is examined and processed into a series of bits terminated by a null, that
+ * are stored in the {@code CollationKey}. When
+ * {@code CollationKey.compareTo(CollationKey)} executes, it performs bitwise
+ * comparison on the bit sequences. This can incur startup cost when creating
+ * the {@code CollationKey}, but once the key is created, binary comparisons
+ * are fast. This approach is recommended when the same strings are to be
+ * compared over and over again.
+ * <p>
+ * On the other hand, implementations of
+ * {@code Collator.compare(String, String)} can examine and process the strings
+ * only until the first characters differ in order. This approach is
+ * recommended if the strings are to be compared only once.
+ * <p>
+ * The following example shows how collation keys can be used to sort a
+ * list of strings:
+ * <blockquote>
+ *
+ * <pre>
+ * // Create an array of CollationKeys for the Strings to be sorted.
+ * Collator myCollator = Collator.getInstance();
+ * CollationKey[] keys = new CollationKey[3];
+ * keys[0] = myCollator.getCollationKey(&quot;Tom&quot;);
+ * keys[1] = myCollator.getCollationKey(&quot;Dick&quot;);
+ * keys[2] = myCollator.getCollationKey(&quot;Harry&quot;);
+ * sort(keys);
+ * <br>
+ * //...
+ * <br>
+ * // Inside body of sort routine, compare keys this way
+ * if( keys[i].compareTo( keys[j] ) &gt; 0 )
+ *    // swap keys[i] and keys[j]
+ * <br>
+ * //...
+ * <br>
+ * // Finally, when we've returned from sort.
+ * System.out.println(keys[0].getSourceString());
+ * System.out.println(keys[1].getSourceString());
+ * System.out.println(keys[2].getSourceString());
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * @see Collator
+ * @see RuleBasedCollator
  */
 public final class CollationKey implements Comparable<CollationKey> {
 
@@ -35,30 +90,29 @@
     }
 
     /**
-     * Compare the receiver to the specified CollationKey to determine the
-     * relative ordering.
+     * Compares this object to the specified collation key object to determine
+     * their relative order.
      * 
      * @param value
-     *            a CollationKey
-     * @return an int < 0 if this CollationKey is less than the specified
-     *         CollationKey, 0 if they are equal, and > 0 if this CollationKey
-     *         is greater
+     *            the collation key object to compare this object to.
+     * @return a negative value if this {@code CollationKey} is less than the
+     *         specified {@code CollationKey}, 0 if they are equal and a
+     *         positive value if this {@code CollationKey} is greater.
      */
     public int compareTo(CollationKey value) {
         return icuKey.compareTo(value.icuKey);
     }
 
     /**
-     * Compares the specified object to this CollationKey and answer if they are
-     * equal. The object must be an instance of CollationKey and have the same
-     * source string and collation key. The instances of CollationKey must have
-     * been created by the same Collator.
+     * Compares the specified object to this {@code CollationKey} and indicates
+     * if they are equal. The object must be an instance of {@code CollationKey}
+     * and have the same source string and collation key. Both instances of
+     * {@code CollationKey} must have been created by the same {@code Collator}.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this CollationKey, false
-     *         otherwise
-     * 
+     *            the object to compare to this object.
+     * @return {@code true} if {@code object} is equal to this collation key;
+     *         {@code false} otherwise.
      * @see #hashCode
      */
     @Override

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Collator.java Thu May  7 08:42:00 2009
@@ -25,9 +25,90 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * Collator is an abstract class which is the root of classes which provide
- * Locale specific String comparison to determine their ordering with respect to
- * each other.
+ * Performs locale-sensitive string comparison. A concrete subclass,
+ * {@link RuleBasedCollator}, allows customization of the collation ordering by
+ * the use of rule sets.
+ * <p>
+ * Following the <a href=http://www.unicode.org>Unicode Consortium</a>'s
+ * specifications for the <a
+ * href="http://www.unicode.org/unicode/reports/tr10/"> Unicode Collation
+ * Algorithm (UCA)</a>, there are 4 different levels of strength used in
+ * comparisons:
+ * <ul>
+ * <li>PRIMARY strength: Typically, this is used to denote differences between
+ * base characters (for example, "a" &lt; "b"). It is the strongest difference.
+ * For example, dictionaries are divided into different sections by base
+ * character.
+ * <li>SECONDARY strength: Accents in the characters are considered secondary
+ * differences (for example, "as" &lt; "&agrave;s" &lt; "at"). Other differences
+ * between letters can also be considered secondary differences, depending on
+ * the language. A secondary difference is ignored when there is a primary
+ * difference anywhere in the strings.
+ * <li>TERTIARY strength: Upper and lower case differences in characters are
+ * distinguished at tertiary strength (for example, "ao" &lt; "Ao" &lt;
+ * "a&ograve;"). In addition, a variant of a letter differs from the base form
+ * on the tertiary strength (such as "A" and "&#9398;"). Another example is the
+ * difference between large and small Kana. A tertiary difference is ignored
+ * when there is a primary or secondary difference anywhere in the strings.
+ * <li>IDENTICAL strength: When all other strengths are equal, the IDENTICAL
+ * strength is used as a tiebreaker. The Unicode code point values of the NFD
+ * form of each string are compared, just in case there is no difference. For
+ * example, Hebrew cantellation marks are only distinguished at this strength.
+ * This strength should be used sparingly, as only code point value differences
+ * between two strings are an extremely rare occurrence. Using this strength
+ * substantially decreases the performance for both comparison and collation key
+ * generation APIs. This strength also increases the size of the collation key.
+ * </ul>
+ * <p>
+ * This {@code Collator} deals only with two decomposition modes, the canonical
+ * decomposition mode and one that does not use any decomposition. The
+ * compatibility decomposition mode
+ * {@code java.text.Collator.FULL_DECOMPOSITION} is not supported here. If the
+ * canonical decomposition mode is set, {@code Collator} handles un-normalized
+ * text properly, producing the same results as if the text were normalized in
+ * NFD. If canonical decomposition is turned off, it is the user's
+ * responsibility to ensure that all text is already in the appropriate form
+ * before performing a comparison or before getting a {@link CollationKey}.
+ * <p>
+ * <em>Examples:</em>
+ * <blockquote>
+ *
+ * <pre>
+ * // Get the Collator for US English and set its strength to PRIMARY
+ * Collator usCollator = Collator.getInstance(Locale.US);
+ * usCollator.setStrength(Collator.PRIMARY);
+ * if (usCollator.compare(&quot;abc&quot;, &quot;ABC&quot;) == 0) {
+ *     System.out.println(&quot;Strings are equivalent&quot;);
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The following example shows how to compare two strings using the collator for
+ * the default locale.
+ * <blockquote>
+ *
+ * <pre>
+ * // Compare two strings in the default locale
+ * Collator myCollator = Collator.getInstance();
+ * myCollator.setDecomposition(Collator.NO_DECOMPOSITION);
+ * if (myCollator.compare(&quot;\u00e0\u0325&quot;, &quot;a\u0325\u0300&quot;) != 0) {
+ *     System.out.println(&quot;\u00e0\u0325 is not equal to a\u0325\u0300 without decomposition&quot;);
+ *     myCollator.setDecomposition(Collator.CANONICAL_DECOMPOSITION);
+ *     if (myCollator.compare(&quot;\u00e0\u0325&quot;, &quot;a\u0325\u0300&quot;) != 0) {
+ *         System.out.println(&quot;Error: \u00e0\u0325 should be equal to a\u0325\u0300 with decomposition&quot;);
+ *     } else {
+ *         System.out.println(&quot;\u00e0\u0325 is equal to a\u0325\u0300 with decomposition&quot;);
+ *     }
+ * } else {
+ *     System.out.println(&quot;Error: \u00e0\u0325 should be not equal to a\u0325\u0300 without decomposition&quot;);
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * @see RuleBasedCollator
+ * @see CollationKey
  */
 public abstract class Collator implements Comparator<Object>, Cloneable {
 
@@ -48,7 +129,8 @@
     public static final int CANONICAL_DECOMPOSITION = 1;
 
     /**
-     * Constant used to specify the decomposition rule.
+     * Constant used to specify the decomposition rule. This value for
+     * decomposition is not supported.
      */
     public static final int FULL_DECOMPOSITION = 2;
 
@@ -99,17 +181,17 @@
     }
 
     /**
-     * Constructs a new instance of this Collator.
+     * Constructs a new {@code Collator} instance.
      */
     protected Collator() {
         super();
     }
 
     /**
-     * Answers a new Collator with the same decomposition rule and strength
-     * value as this Collator.
+     * Returns a new collator with the same decomposition mode and
+     * strength value as this collator.
      * 
-     * @return a shallow copy of this Collator
+     * @return a shallow copy of this collator.
      * @see java.lang.Cloneable
      */
     @Override
@@ -124,45 +206,45 @@
     }
 
     /**
-     * Compares the two objects to determine their relative ordering. The
-     * objects must be Strings.
+     * Compares two objects to determine their relative order. The objects must
+     * be strings.
      * 
      * @param object1
-     *            the first String to compare
+     *            the first string to compare.
      * @param object2
-     *            the second String to compare
-     * @return an int < 0 if object1 is less than object2, 0 if they are equal,
-     *         and > 0 if object1 is greater than object2
-     * 
-     * @exception ClassCastException
-     *                when the objects are not Strings
+     *            the second string to compare.
+     * @return a negative value if {@code object1} is less than {@code object2},
+     *         0 if they are equal, and a positive value if {@code object1} is
+     *         greater than {@code object2}.
+     * @throws ClassCastException
+     *         if {@code object1} or {@code object2} is not a {@code String}.
      */
     public int compare(Object object1, Object object2) {
         return compare((String) object1, (String) object2);
     }
 
     /**
-     * Compares the two Strings to determine their relative ordering.
+     * Compares two strings to determine their relative order.
      * 
      * @param string1
-     *            the first String to compare
+     *            the first string to compare.
      * @param string2
-     *            the second String to compare
-     * @return an int < 0 if string1 is less than string2, 0 if they are equal,
-     *         and > 0 if string1 is greater than string2
+     *            the second string to compare.
+     * @return a negative value if {@code string1} is less than {@code string2},
+     *         0 if they are equal and a positive value if {@code string1} is
+     *         greater than {@code string2}.
      */
     public abstract int compare(String string1, String string2);
 
     /**
-     * Compares the specified object to this Collator and answer if they are
-     * equal. The object must be an instance of Collator and have the same
-     * strength and decomposition values.
+     * Compares this collator with the specified object and indicates if they
+     * are equal.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this Collator, false
-     *         otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if {@code object} is a {@code Collator} object and
+     *         it has the same strength and decomposition values as this
+     *         collator; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -176,65 +258,68 @@
     }
 
     /**
-     * Compares the two Strings using the collation rules to determine if they
-     * are equal.
+     * Compares two strings using the collation rules to determine if they are
+     * equal.
      * 
      * @param string1
-     *            the first String to compare
+     *            the first string to compare.
      * @param string2
-     *            the second String to compare
-     * @return true if the strings are equal using the collation rules, false
-     *         otherwise
+     *            the second string to compare.
+     * @return {@code true} if {@code string1} and {@code string2} are equal
+     *         using the collation rules, false otherwise.
      */
     public boolean equals(String string1, String string2) {
         return compare(string1, string2) == 0;
     }
 
     /**
-     * Gets the list of installed Locales which support Collator.
+     * Gets the list of installed {@link java.util.Locale} objects which support
+     * {@code Collator}.
      * 
-     * @return an array of Locale
+     * @return an array of {@code Locale}.
      */
     public static Locale[] getAvailableLocales() {
         return com.ibm.icu.text.Collator.getAvailableLocales();
     }
 
     /**
-     * Answers a CollationKey for the specified String for this Collator with
-     * the current decomposition rule and strength value.
+     * Returns a {@link CollationKey} for the specified string for this collator
+     * with the current decomposition rule and strength value.
      * 
      * @param string
-     *            the collation key.
-     * @return a CollationKey
+     *            the source string that is converted into a collation key.
+     * @return the collation key for {@code string}.
      */
     public abstract CollationKey getCollationKey(String string);
 
     /**
-     * Answers the decomposition rule for this Collator.
+     * Returns the decomposition rule for this collator.
      * 
-     * @return the decomposition rule, either NO_DECOMPOSITION,
-     *         CANONICAL_DECOMPOSITION or FULL_DECOMPOSITION
+     * @return the decomposition rule, either {@code NO_DECOMPOSITION} or
+     *         {@code CANONICAL_DECOMPOSITION}. {@code FULL_DECOMPOSITION} is
+     *         not supported.
      */
     public int getDecomposition() {
         return decompositionMode_ICU_Java(this.icuColl.getDecomposition());
     }
 
     /**
-     * Answers a Collator instance which is appropriate for the default Locale.
+     * Returns a {@code Collator} instance which is appropriate for the default
+     * {@code Locale}.
      * 
-     * @return a Collator
+     * @return the collator for the default locale.
      */
     public static Collator getInstance() {
         return getInstance(Locale.getDefault());
     }
 
     /**
-     * Answers a Collator instance which is appropriate for the specified
-     * Locale.
+     * Returns a {@code Collator} instance which is appropriate for the
+     * specified {@code Locale}.
      * 
      * @param locale
-     *            the Locale
-     * @return a Collator
+     *            the locale.
+     * @return the collator for {@code locale}.
      */
     public static Collator getInstance(Locale locale) {
         String key = locale.toString();
@@ -249,20 +334,19 @@
     }
 
     /**
-     * Answers the strength value for this Collator.
+     * Returns the strength value for this collator.
      * 
-     * @return the strength value, either PRIMARY, SECONDARY, TERTIARY, or
-     *         IDENTICAL
+     * @return the strength value, either PRIMARY, SECONDARY, TERTIARY or
+     *         IDENTICAL.
      */
     public int getStrength() {
         return strength_ICU_Java(this.icuColl.getStrength());
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
+     * Returns an integer hash code for this collator.
      * 
-     * @return the receiver's hash
+     * @return this collator's hash code.
      * 
      * @see #equals(Object)
      * @see #equals(String, String)
@@ -271,28 +355,28 @@
     public abstract int hashCode();
 
     /**
-     * Sets the decomposition rule for this Collator.
+     * Sets the decomposition rule for this collator.
      * 
      * @param value
-     *            the decomposition rule, either NO_DECOMPOSITION,
-     *            CANONICAL_DECOMPOSITION or FULL_DECOMPOSITION
-     * 
-     * @exception IllegalArgumentException
-     *                when the decomposition rule is not valid
+     *            the decomposition rule, either {@code NO_DECOMPOSITION} or
+     *            {@code CANONICAL_DECOMPOSITION}. {@code FULL_DECOMPOSITION}
+     *            is not supported.
+     * @throws IllegalArgumentException
+     *            if the provided decomposition rule is not valid. This includes
+     *            {@code FULL_DECOMPOSITION}.
      */
     public void setDecomposition(int value) {
         this.icuColl.setDecomposition(decompositionMode_Java_ICU(value));
     }
 
     /**
-     * Sets the strength value for this Collator.
+     * Sets the strength value for this collator.
      * 
      * @param value
      *            the strength value, either PRIMARY, SECONDARY, TERTIARY, or
-     *            IDENTICAL
-     * 
-     * @exception IllegalArgumentException
-     *                when the strength value is not valid
+     *            IDENTICAL.
+     * @throws IllegalArgumentException
+     *            if the provided strength value is not valid.
      */
     public void setStrength(int value) {
         this.icuColl.setStrength(strength_Java_ICU(value));

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormat.java Thu May  7 08:42:00 2009
@@ -27,143 +27,270 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * DateFormat is the abstract superclass of formats which format and parse
- * Dates.
+ * An abstract class for date/time formatting subclasses which formats and
+ * parses dates or time in a language-independent manner. The date/time
+ * formatting subclass, such as {@link SimpleDateFormat}, allows for formatting
+ * (i.e., date -> text), parsing (text -> date), and normalization. The date is
+ * represented as a {@code Date} object or as the milliseconds since January 1,
+ * 1970, 00:00:00 GMT.
+ * <p>
+ * DateFormat provides many class methods for obtaining default date/time
+ * formatters based on the default or a given locale and a number of formatting
+ * styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More
+ * details and examples for using these styles are provided in the method
+ * descriptions.
+ * <p>
+ * {@code DateFormat} helps you to format and parse dates for any locale. Your
+ * code can be completely independent of the locale conventions for months, days
+ * of the week, or even the calendar format: lunar vs. solar.
+ * <p>
+ * To format a date for the current Locale, use one of the static factory
+ * methods:
+ * <blockquote>
+ *
+ * <pre>
+ * myString = DateFormat.getDateInstance().format(myDate);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * If you are formatting multiple dates, it is more efficient to get the format
+ * and use it multiple times so that the system doesn't have to fetch the
+ * information about the local language and country conventions multiple times.
+ * <blockquote>
+ *
+ * <pre>
+ * DateFormat df = DateFormat.getDateInstance();
+ * for (int i = 0; i &lt; a.length; ++i) {
+ *     output.println(df.format(myDate[i]) + &quot;; &quot;);
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * To format a number for a different locale, specify it in the call to
+ * {@code getDateInstance}:
+ * <blockquote>
+ *
+ * <pre>
+ * DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * {@code DateFormat} can also be used to parse strings:
+ * <blockquote>
+ *
+ * <pre>
+ * myDate = df.parse(myString);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Use {@code getDateInstance} to get the normal date format for a country.
+ * Other static factory methods are available: Use {@code getTimeInstance} to
+ * get the time format for a country. Use {@code getDateTimeInstance} to get the
+ * date and time format. You can pass in different options to these factory
+ * methods to control the length of the result; from SHORT to MEDIUM to LONG to
+ * FULL. The exact result depends on the locale, but generally:
+ * <ul>
+ * <li>SHORT is completely numeric, such as 12.13.52 or 3:30pm
+ * <li>MEDIUM is longer, such as Jan 12, 1952
+ * <li>LONG is longer, such as January 12, 1952 or 3:30:32pm
+ * <li>FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD
+ * or 3:30:42pm PST.
+ * </ul>
+ * <p>
+ * If needed, the time zone can be set on the format. For even greater control
+ * over the formatting or parsing, try casting the {@code DateFormat} you get
+ * from the factory methods to a {@code SimpleDateFormat}. This will work for
+ * the majority of countries; just remember to put it in a try block in case you
+ * encounter an unusual one.
+ * <p>
+ * There are versions of the parse and format methods which use
+ * {@code ParsePosition} and {@code FieldPosition} to allow you to
+ * <ul>
+ * <li>progressively parse through pieces of a string;
+ * <li>align any particular field.
+ * </ul>
+ * <h4>Synchronization</h4>
+ * <p>
+ * Date formats are not synchronized. It is recommended to create separate
+ * format instances for each thread. If multiple threads access a format
+ * concurrently, it must be synchronized externally.
+ *
+ * @see NumberFormat
+ * @see SimpleDateFormat
+ * @see Calendar
+ * @see TimeZone
  */
 public abstract class DateFormat extends Format {
 
     private static final long serialVersionUID = 7218322306649953788L;
 
+    /**
+     * The calendar that this {@code DateFormat} uses to format a number
+     * representing a date.
+     */
     protected Calendar calendar;
 
+    /**
+     * The number format used to format a number.
+     */
     protected NumberFormat numberFormat;
 
     /**
-     * Format style constant.
+     * The format style constant defining the default format style. The default
+     * is MEDIUM.
      */
     public final static int DEFAULT = 2;
 
     /**
-     * Format style constant.
+     * The format style constant defining the full style.
      */
     public final static int FULL = 0;
 
     /**
-     * Format style constant.
+     * The format style constant defining the long style.
      */
     public final static int LONG = 1;
 
     /**
-     * Format style constant.
+     * The format style constant defining the medium style.
      */
     public final static int MEDIUM = 2;
 
     /**
-     * Format style constant.
+     * The format style constant defining the short style.
      */
     public final static int SHORT = 3;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'G' field alignment, corresponds
+     * to the {@link Calendar#ERA} field.
      */
     public final static int ERA_FIELD = 0;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'y' field alignment, corresponds
+     * to the {@link Calendar#YEAR} field.
      */
     public final static int YEAR_FIELD = 1;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'M' field alignment, corresponds
+     * to the {@link Calendar#MONTH} field.
      */
     public final static int MONTH_FIELD = 2;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'd' field alignment, corresponds
+     * to the {@link Calendar#DATE} field.
      */
     public final static int DATE_FIELD = 3;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'k' field alignment, corresponds
+     * to the {@link Calendar#HOUR_OF_DAY} field. {@code HOUR_OF_DAY1_FIELD} is
+     * used for the one-based 24-hour clock. For example, 23:59 + 01:00 results
+     * in 24:59.
      */
     public final static int HOUR_OF_DAY1_FIELD = 4;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'H' field alignment, corresponds
+     * to the {@link Calendar#HOUR_OF_DAY} field. {@code HOUR_OF_DAY0_FIELD} is
+     * used for the zero-based 24-hour clock. For example, 23:59 + 01:00 results
+     * in 00:59.
      */
     public final static int HOUR_OF_DAY0_FIELD = 5;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'm' field alignment, corresponds to the
+     * {@link Calendar#MINUTE} field.
      */
     public final static int MINUTE_FIELD = 6;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 's' field alignment, corresponds to the
+     * {@link Calendar#SECOND} field.
      */
     public final static int SECOND_FIELD = 7;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'S' field alignment, corresponds to the
+     * {@link Calendar#MILLISECOND} field.
      */
     public final static int MILLISECOND_FIELD = 8;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'E' field alignment, corresponds to the
+     * {@link Calendar#DAY_OF_WEEK} field.
      */
     public final static int DAY_OF_WEEK_FIELD = 9;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'D' field alignment, corresponds to the
+     * {@link Calendar#DAY_OF_YEAR} field.
      */
     public final static int DAY_OF_YEAR_FIELD = 10;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'F' field alignment, corresponds to the
+     * {@link Calendar#DAY_OF_WEEK_IN_MONTH} field.
      */
     public final static int DAY_OF_WEEK_IN_MONTH_FIELD = 11;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'w' field alignment, corresponds to the
+     * {@link Calendar#WEEK_OF_YEAR} field.
      */
     public final static int WEEK_OF_YEAR_FIELD = 12;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'W' field alignment, corresponds to the
+     * {@link Calendar#WEEK_OF_MONTH} field.
      */
     public final static int WEEK_OF_MONTH_FIELD = 13;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'a' field alignment, corresponds to the
+     * {@link Calendar#AM_PM} field.
      */
     public final static int AM_PM_FIELD = 14;
 
     /**
-     * Field constant.
+     * FieldPosition selector for 'h' field alignment, corresponding to the
+     * {@link Calendar#HOUR} field. {@code HOUR1_FIELD} is used for the
+     * one-based 12-hour clock. For example, 11:30 PM + 1 hour results in 12:30
+     * AM.
      */
     public final static int HOUR1_FIELD = 15;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'z' field alignment, corresponds
+     * to the {@link Calendar#ZONE_OFFSET} and {@link Calendar#DST_OFFSET}
+     * fields.
      */
     public final static int HOUR0_FIELD = 16;
 
     /**
-     * Field constant.
+     * The {@code FieldPosition} selector for 'z' field alignment, corresponds
+     * to the {@link Calendar#ZONE_OFFSET} and {@link Calendar#DST_OFFSET}
+     * fields.
      */
     public final static int TIMEZONE_FIELD = 17;
 
     /**
-     * Constructs a new instance of DateFormat.
-     * 
+     * Constructs a new instance of {@code DateFormat}.
      */
     protected DateFormat() {
     }
 
     /**
-     * Answers a new instance of DateFormat with the same properties.
+     * Returns a new instance of {@code DateFormat} with the same properties.
      * 
-     * @return a shallow copy of this DateFormat
+     * @return a shallow copy of this {@code DateFormat}.
      * 
      * @see java.lang.Cloneable
      */
@@ -176,15 +303,14 @@
     }
 
     /**
-     * Compares the specified object to this DateFormat and answer if they are
-     * equal. The object must be an instance of DateFormat with the same
-     * properties.
+     * Compares this date format with the specified object and indicates if they
+     * are equal.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this DateFormat, false
-     *         otherwise
-     * 
+     *            the object to compare with this date format.
+     * @return {@code true} if {@code object} is a {@code DateFormat} object and
+     *         it has the same properties as this date format; {@code false}
+     *         otherwise.
      * @see #hashCode
      */
     @Override
@@ -207,23 +333,27 @@
     }
 
     /**
-     * Formats the specified object into the specified StringBuffer using the
-     * rules of this DateFormat. If the field specified by the FieldPosition is
-     * formatted, set the begin and end index of the formatted field in the
-     * FieldPosition.
-     * 
+     * Formats the specified object as a string using the pattern of this date
+     * format and appends the string to the specified string buffer.
+     * <p>
+     * If the {@code field} member of {@code field} contains a value specifying
+     * a format field, then its {@code beginIndex} and {@code endIndex} members
+     * will be updated with the position of the first occurrence of this field
+     * in the formatted text.
+     *
      * @param object
-     *            the object to format, must be a Date or a Number. If the
-     *            object is a Number, a Date is constructed using the
-     *            <code>longValue()</code> of the Number.
+     *            the source object to format, must be a {@code Date} or a
+     *            {@code Number}. If {@code object} is a number then a date is
+     *            constructed using the {@code longValue()} of the number.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted date/time to.
      * @param field
-     *            the FieldPosition
-     * @return the StringBuffer parameter <code>buffer</code>
-     * 
-     * @exception IllegalArgumentException
-     *                when the object is not a Date or a Number
+     *            on input: an optional alignment field; on output: the offsets
+     *            of the alignment field in the formatted text.
+     * @return the string buffer.
+     * @throws IllegalArgumentException
+     *            if {@code object} is neither a {@code Date} nor a
+     *            {@code Number} instance.
      */
     @Override
     public final StringBuffer format(Object object, StringBuffer buffer,
@@ -239,11 +369,11 @@
     }
 
     /**
-     * Formats the specified Date using the rules of this DateFormat.
+     * Formats the specified date using the rules of this date format.
      * 
      * @param date
-     *            the Date to format
-     * @return the formatted String
+     *            the date to format.
+     * @return the formatted string.
      */
     public final String format(Date date) {
         return format(date, new StringBuffer(), new FieldPosition(0))
@@ -251,57 +381,65 @@
     }
 
     /**
-     * Formats the specified Date into the specified StringBuffer using the
-     * rules of this DateFormat. If the field specified by the FieldPosition is
-     * formatted, set the begin and end index of the formatted field in the
-     * FieldPosition.
-     * 
+     * Formats the specified date as a string using the pattern of this date
+     * format and appends the string to the specified string buffer.
+     * <p>
+     * If the {@code field} member of {@code field} contains a value specifying
+     * a format field, then its {@code beginIndex} and {@code endIndex} members
+     * will be updated with the position of the first occurrence of this field
+     * in the formatted text.
+     *
      * @param date
-     *            the Date to format
+     *            the date to format.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted date/time to.
      * @param field
-     *            the FieldPosition
-     * @return the StringBuffer parameter <code>buffer</code>
+     *            on input: an optional alignment field; on output: the offsets
+     *            of the alignment field in the formatted text.
+     * @return the string buffer.
      */
     public abstract StringBuffer format(Date date, StringBuffer buffer,
             FieldPosition field);
 
     /**
-     * Gets the list of installed Locales which support DateFormat.
+     * Gets the list of installed locales which support {@code DateFormat}.
      * 
-     * @return an array of Locale
+     * @return an array of locales.
      */
     public static Locale[] getAvailableLocales() {
         return Locale.getAvailableLocales();
     }
 
     /**
-     * Answers the Calendar used by this DateFormat.
+     * Returns the calendar used by this {@code DateFormat}.
      * 
-     * @return a Calendar
+     * @return the calendar used by this date format.
      */
     public Calendar getCalendar() {
         return calendar;
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing dates in the
-     * DEFAULT style for the default Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing dates in
+     * the DEFAULT style for the default locale.
      * 
-     * @return a DateFormat
+     * @return the {@code DateFormat} instance for the default style and locale.
      */
     public final static DateFormat getDateInstance() {
         return getDateInstance(DEFAULT);
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing dates in the
-     * specified style for the default Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing dates in
+     * the specified style for the default locale.
      * 
      * @param style
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
-     * @return a DateFormat
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
+     * @return the {@code DateFormat} instance for {@code style} and the default
+     *         locale.
+     * @throws IllegalArgumentException
+     *             if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+     *             DEFAULT.
      */
     public final static DateFormat getDateInstance(int style) {
         checkDateStyle(style);
@@ -309,14 +447,18 @@
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing dates in the
-     * specified style for the specified Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing dates in
+     * the specified style for the specified locale.
      * 
      * @param style
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @param locale
-     *            the Locale
-     * @return a DateFormat
+     *            the locale.
+     * @throws IllegalArgumentException
+     *             if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+     *             DEFAULT.
+     * @return the {@code DateFormat} instance for {@code style} and
+     *         {@code locale}.
      */
     public final static DateFormat getDateInstance(int style, Locale locale) {
         checkDateStyle(style);
@@ -325,25 +467,28 @@
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing dates and times
-     * in the DEFAULT style for the default Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing dates
+     * and time values in the DEFAULT style for the default locale.
      * 
-     * @return a DateFormat
+     * @return the {@code DateFormat} instance for the default style and locale.
      */
     public final static DateFormat getDateTimeInstance() {
         return getDateTimeInstance(DEFAULT, DEFAULT);
     }
 
     /**
-     * Answers a <code>DateFormat</code> instance for the formatting and
-     * parsing of both dates and times in the manner appropriate to the default
-     * Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing of both
+     * dates and time values in the manner appropriate for the default locale.
      * 
      * @param dateStyle
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @param timeStyle
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
-     * @return a DateFormat
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
+     * @return the {@code DateFormat} instance for {@code dateStyle},
+     *         {@code timeStyle} and the default locale.
+     * @throws IllegalArgumentException
+     *             if {@code dateStyle} or {@code timeStyle} is not one of
+     *             SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      */
     public final static DateFormat getDateTimeInstance(int dateStyle,
             int timeStyle) {
@@ -353,16 +498,20 @@
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing dates and times
-     * in the specified styles for the specified Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing dates
+     * and time values in the specified styles for the specified locale.
      * 
      * @param dateStyle
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @param timeStyle
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @param locale
-     *            the Locale
-     * @return a DateFormat
+     *            the locale.
+     * @return the {@code DateFormat} instance for {@code dateStyle},
+     *         {@code timeStyle} and {@code locale}.
+     * @throws IllegalArgumentException
+     *             if {@code dateStyle} or {@code timeStyle} is not one of
+     *             SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      */
     public final static DateFormat getDateTimeInstance(int dateStyle,
             int timeStyle, Locale locale) {
@@ -373,19 +522,20 @@
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing dates and times
-     * in the SHORT style for the default Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing dates
+     * and times in the SHORT style for the default locale.
      * 
-     * @return a DateFormat
+     * @return the {@code DateFormat} instance for the SHORT style and default
+     *         locale.
      */
     public final static DateFormat getInstance() {
         return getDateTimeInstance(SHORT, SHORT);
     }
 
     /**
-     * Answers the NumberFormat used by this DateFormat.
+     * Returns the {@code NumberFormat} used by this {@code DateFormat}.
      * 
-     * @return a NumberFormat
+     * @return the {@code NumberFormat} used by this date format.
      */
     public NumberFormat getNumberFormat() {
         return numberFormat;
@@ -413,22 +563,26 @@
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing times in the
-     * DEFAULT style for the default Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing time
+     * values in the DEFAULT style for the default locale.
      * 
-     * @return a DateFormat
+     * @return the {@code DateFormat} instance for the default style and locale.
      */
     public final static DateFormat getTimeInstance() {
         return getTimeInstance(DEFAULT);
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing times in the
-     * specified style for the default Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing time
+     * values in the specified style for the default locale.
      * 
      * @param style
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
-     * @return a DateFormat
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
+     * @return the {@code DateFormat} instance for {@code style} and the default
+     *         locale.
+     * @throws IllegalArgumentException
+     *             if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+     *             DEFAULT.
      */
     public final static DateFormat getTimeInstance(int style) {
         checkTimeStyle(style);
@@ -436,14 +590,18 @@
     }
 
     /**
-     * Answers a DateFormat instance for formatting and parsing times in the
-     * specified style for the specified Locale.
+     * Returns a {@code DateFormat} instance for formatting and parsing time
+     * values in the specified style for the specified locale.
      * 
      * @param style
-     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT
+     *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @param locale
-     *            the Locale
-     * @return a DateFormat
+     *            the locale.
+     * @throws IllegalArgumentException
+     *             if {@code style} is not one of SHORT, MEDIUM, LONG, FULL, or
+     *             DEFAULT.
+     * @return the {@code DateFormat} instance for {@code style} and
+     *         {@code locale}.
      */
     public final static DateFormat getTimeInstance(int style, Locale locale) {
         checkTimeStyle(style);
@@ -452,22 +610,14 @@
     }
 
     /**
-     * Answers the TimeZone of the Calendar used by this DateFormat.
+     * Returns the time zone of this date format's calendar.
      * 
-     * @return a TimeZone
+     * @return the time zone of the calendar used by this date format.
      */
     public TimeZone getTimeZone() {
         return calendar.getTimeZone();
     }
 
-    /**
-     * 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() {
         return calendar.getFirstDayOfWeek()
@@ -478,24 +628,23 @@
     }
 
     /**
-     * Answers if the Calendar used by this DateFormat is lenient.
+     * Indicates whether the calendar used by this date format is lenient.
      * 
-     * @return true when the Calendar is lenient, false otherwise
+     * @return {@code true} if the calendar is lenient; {@code false} otherwise.
      */
     public boolean isLenient() {
         return calendar.isLenient();
     }
 
     /**
-     * Parse a Date from the specified String using the rules of this
-     * DateFormat.
+     * Parses a date from the specified string using the rules of this date
+     * format.
      * 
      * @param string
-     *            the String to parse
-     * @return the Date resulting from the parse
-     * 
-     * @exception ParseException
-     *                when an error occurs during parsing
+     *            the string to parse.
+     * @return the {@code Date} resulting from the parsing.
+     * @throws ParseException
+     *         if an error occurs during parsing.
      */
     public Date parse(String string) throws ParseException {
         ParsePosition position = new ParsePosition(0);
@@ -509,32 +658,52 @@
     }
 
     /**
-     * Parse a Date from the specified String starting at the index specified by
-     * the ParsePosition. If the string is successfully parsed, the index of the
-     * ParsePosition is updated to the index following the parsed text.
-     * 
+     * Parses a date from the specified string starting at the index specified
+     * by {@code position}. If the string is successfully parsed then the index
+     * of the {@code ParsePosition} is updated to the index following the parsed
+     * text. On error, the index is unchanged and the error index of {@code
+     * ParsePosition} is set to the index where the error occurred.
+     * <p>
+     * By default, parsing is lenient: If the input is not in the form used by
+     * this object's format method but can still be parsed as a date, then the
+     * parse succeeds. Clients may insist on strict adherence to the format by
+     * calling {@code setLenient(false)}.
+     *
      * @param string
-     *            the String to parse
+     *            the string to parse.
      * @param position
-     *            the ParsePosition, updated on return with the index following
-     *            the parsed text, or on error the index is unchanged and the
-     *            error index is set to the index where the error occurred
-     * @return the Date resulting from the parse, or null if there is an error
+     *            input/output parameter, specifies the start index in {@code
+     *            string} from where to start parsing. If parsing is successful,
+     *            it is updated with the index following the parsed text; on
+     *            error, the index is unchanged and the error index is set to
+     *            the index where the error occurred.
+     * @return the date resulting from the parse, or {@code null} if there is an
+     *         error.
      */
     public abstract Date parse(String string, ParsePosition position);
 
     /**
-     * Parse a Date from the specified String starting at the index specified by
-     * the ParsePosition. If the string is successfully parsed, the index of the
-     * ParsePosition is updated to the index following the parsed text.
-     * 
+     * Parses a date from the specified string starting at the index specified
+     * by {@code position}. If the string is successfully parsed then the index
+     * of the {@code ParsePosition} is updated to the index following the parsed
+     * text. On error, the index is unchanged and the error index of
+     * {@code ParsePosition} is set to the index where the error occurred.
+     * <p>
+     * By default, parsing is lenient: If the input is not in the form used by
+     * this object's format method but can still be parsed as a date, then the
+     * parse succeeds. Clients may insist on strict adherence to the format by
+     * calling {@code setLenient(false)}.
+     *
      * @param string
-     *            the String to parse
+     *            the string to parse.
      * @param position
-     *            the ParsePosition, updated on return with the index following
-     *            the parsed text, or on error the index is unchanged and the
-     *            error index is set to the index where the error occurred
-     * @return the Date resulting from the parse, or null if there is an error
+     *            input/output parameter, specifies the start index in
+     *            {@code string} from where to start parsing. If parsing is
+     *            successful, it is updated with the index following the parsed
+     *            text; on error, the index is unchanged and the error index
+     *            is set to the index where the error occurred.
+     * @return the date resulting from the parsing, or {@code null} if there is
+     *         an error.
      */
     @Override
     public Object parseObject(String string, ParsePosition position) {
@@ -542,40 +711,44 @@
     }
 
     /**
-     * Sets the Calendar used by this DateFormat.
+     * Sets the calendar used by this date format.
      * 
      * @param cal
-     *            the Calendar
+     *            the new calendar.
      */
     public void setCalendar(Calendar cal) {
         calendar = cal;
     }
 
     /**
-     * Sets if the Calendar used by this DateFormat is lenient.
+     * Specifies whether or not date/time parsing shall be lenient. With lenient
+     * parsing, the parser may use heuristics to interpret inputs that do not
+     * precisely match this object's format. With strict parsing, inputs must
+     * match this object's format.
      * 
      * @param value
-     *            true to set the Calendar to be lenient, false otherwise
+     *            {@code true} to set the calendar to be lenient, {@code false}
+     *            otherwise.
      */
     public void setLenient(boolean value) {
         calendar.setLenient(value);
     }
 
     /**
-     * Sets the NumberFormat used by this DateFormat.
+     * Sets the {@code NumberFormat} used by this date format.
      * 
      * @param format
-     *            the NumberFormat
+     *            the new number format.
      */
     public void setNumberFormat(NumberFormat format) {
         numberFormat = format;
     }
 
     /**
-     * Sets the TimeZone of the Calendar used by this DateFormat.
+     * Sets the time zone of the calendar used by this date format.
      * 
      * @param timezone
-     *            the TimeZone
+     *            the new time zone.
      */
     public void setTimeZone(TimeZone timezone) {
         calendar.setTimeZone(timezone);
@@ -583,12 +756,11 @@
 
     /**
      * The instances of this inner class are used as attribute keys and values
-     * in AttributedCharacterIterator that
-     * SimpleDateFormat.formatToCharacterIterator() method returns.
+     * in {@code AttributedCharacterIterator} that the
+     * {@link SimpleDateFormat#formatToCharacterIterator(Object)} method returns.
      * <p>
-     * There is no public constructor to this class, the only instances are the
+     * There is no public constructor in this class, the only instances are the
      * constants defined here.
-     * <p>
      */
     public static class Field extends Format.Field {
 
@@ -596,58 +768,117 @@
 
         private static Hashtable<Integer, Field> table = new Hashtable<Integer, Field>();
 
+        /**
+         * Marks the era part of a date.
+         */
         public final static Field ERA = new Field("era", Calendar.ERA); //$NON-NLS-1$
 
+        /**
+         * Marks the year part of a date.
+         */
         public final static Field YEAR = new Field("year", Calendar.YEAR); //$NON-NLS-1$
 
+        /**
+         * Marks the month part of a date.
+         */
         public final static Field MONTH = new Field("month", Calendar.MONTH); //$NON-NLS-1$
 
+        /**
+         * Marks the hour of the day part of a date (0-11).
+         */
         public final static Field HOUR_OF_DAY0 = new Field("hour of day", //$NON-NLS-1$
                 Calendar.HOUR_OF_DAY);
 
+        /**
+         * Marks the hour of the day part of a date (1-12).
+         */
         public final static Field HOUR_OF_DAY1 = new Field("hour of day 1", -1); //$NON-NLS-1$
 
+        /**
+         * Marks the minute part of a time.
+         */
         public final static Field MINUTE = new Field("minute", Calendar.MINUTE); //$NON-NLS-1$
 
+        /**
+         * Marks the second part of a time.
+         */
         public final static Field SECOND = new Field("second", Calendar.SECOND); //$NON-NLS-1$
 
+        /**
+         * Marks the millisecond part of a time.
+         */
         public final static Field MILLISECOND = new Field("millisecond", //$NON-NLS-1$
                 Calendar.MILLISECOND);
 
+        /**
+         * Marks the day of the week part of a date.
+         */
         public final static Field DAY_OF_WEEK = new Field("day of week", //$NON-NLS-1$
                 Calendar.DAY_OF_WEEK);
 
+        /**
+         * Marks the day of the month part of a date.
+         */
         public final static Field DAY_OF_MONTH = new Field("day of month", //$NON-NLS-1$
                 Calendar.DAY_OF_MONTH);
 
+        /**
+         * Marks the day of the year part of a date.
+         */
         public final static Field DAY_OF_YEAR = new Field("day of year", //$NON-NLS-1$
                 Calendar.DAY_OF_YEAR);
 
+        /**
+         * Marks the day of the week in the month part of a date.
+         */
         public final static Field DAY_OF_WEEK_IN_MONTH = new Field(
                 "day of week in month", Calendar.DAY_OF_WEEK_IN_MONTH); //$NON-NLS-1$
 
+        /**
+         * Marks the week of the year part of a date.
+         */
         public final static Field WEEK_OF_YEAR = new Field("week of year", //$NON-NLS-1$
                 Calendar.WEEK_OF_YEAR);
 
+        /**
+         * Marks the week of the month part of a date.
+         */
         public final static Field WEEK_OF_MONTH = new Field("week of month", //$NON-NLS-1$
                 Calendar.WEEK_OF_MONTH);
 
+        /**
+         * Marks the time indicator part of a date.
+         */
         public final static Field AM_PM = new Field("am pm", Calendar.AM_PM); //$NON-NLS-1$
 
+        /**
+         * Marks the hour part of a date (0-11).
+         */
         public final static Field HOUR0 = new Field("hour", Calendar.HOUR); //$NON-NLS-1$
 
+        /**
+         * Marks the hour part of a date (1-12).
+         */
         public final static Field HOUR1 = new Field("hour 1", -1); //$NON-NLS-1$
 
+        /**
+         * Marks the time zone part of a date.
+         */
         public final static Field TIME_ZONE = new Field("time zone", -1); //$NON-NLS-1$
 
         /**
-         * The Calendar field that this Field represents.
+         * The calendar field that this field represents.
          */
         private int calendarField = -1;
 
         /**
-         * Constructs a new instance of DateFormat.Field with the given
+         * Constructs a new instance of {@code DateFormat.Field} with the given
          * fieldName and calendar field.
+         *
+         * @param fieldName
+         *            the field name.
+         * @param calendarField
+         *            the calendar field type of the field.
          */
         protected Field(String fieldName, int calendarField) {
             super(fieldName);
@@ -659,20 +890,25 @@
         }
 
         /**
-         * Answers the Calendar field this Field represents
+         * Returns the Calendar field that this field represents.
          * 
-         * @return int calendar field
+         * @return the calendar field.
          */
         public int getCalendarField() {
             return calendarField;
         }
 
         /**
-         * Answers the DateFormat.Field instance for the given calendar field
+         * Returns the {@code DateFormat.Field} instance for the given calendar
+         * field.
          * 
          * @param calendarField
-         *            a calendar field constant
-         * @return null if there is no Field for this calendar field
+         *            a calendar field constant.
+         * @return the {@code DateFormat.Field} corresponding to
+         *         {@code calendarField}.
+         * @throws IllegalArgumentException
+         *             if {@code calendarField} is negative or greater than the
+         *             field count of {@code Calendar}.
          */
         public static Field ofCalendarField(int calendarField) {
             if (calendarField < 0 || calendarField >= Calendar.FIELD_COUNT) {
@@ -683,8 +919,12 @@
         }
 
         /**
-         * Serialization method resolve instances to the constant
-         * DateFormat.Field values
+         * Resolves instances that are deserialized to the constant
+         * {@code DateFormat.Field} values.
+         *
+         * @return the resolved field object.
+         * @throws InvalidObjectException
+         *             if an error occurs while resolving the field object.
          */
         @Override
         protected Object readResolve() throws InvalidObjectException {



Mime
View raw message