harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772552 [3/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/DateFormatSymbols.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java Thu May  7 08:42:00 2009
@@ -22,8 +22,41 @@
 import java.util.Locale;
 
 /**
- * DateFormatSymbols holds the Strings used in the formating and parsing of
- * dates and times.
+ * Encapsulates localizable date-time formatting data, such as the names of the
+ * months, the names of the days of the week, and the time zone data.
+ * {@code DateFormat} and {@code SimpleDateFormat} both use
+ * {@code DateFormatSymbols} to encapsulate this information.
+ * <p>
+ * Typically you shouldn't use {@code DateFormatSymbols} directly. Rather, you
+ * are encouraged to create a date/time formatter with the {@code DateFormat}
+ * class's factory methods: {@code getTimeInstance}, {@code getDateInstance},
+ * or {@code getDateTimeInstance}. These methods automatically create a
+ * {@code DateFormatSymbols} for the formatter so that you don't have to. After
+ * the formatter is created, you may modify its format pattern using the
+ * {@code setPattern} method. For more information about creating formatters
+ * using {@code DateFormat}'s factory methods, see {@link DateFormat}.
+ * <p>
+ * If you decide to create a date/time formatter with a specific format pattern
+ * for a specific locale, you can do so with:
+ * <blockquote>
+ *
+ * <pre>
+ * new SimpleDateFormat(aPattern, new DateFormatSymbols(aLocale)).
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * {@code DateFormatSymbols} objects can be cloned. When you obtain a
+ * {@code DateFormatSymbols} object, feel free to modify the date/time
+ * formatting data. For instance, you can replace the localized date/time format
+ * pattern characters with the ones that you feel easy to remember or you can
+ * change the representative cities to your favorite ones.
+ * <p>
+ * New {@code DateFormatSymbols} subclasses may be added to support
+ * {@code SimpleDateFormat} for date/time formatting for additional locales.
+ *
+ * @see DateFormat
+ * @see SimpleDateFormat
  */
 public class DateFormatSymbols implements Serializable, Cloneable {
 
@@ -36,19 +69,19 @@
     String[][] zoneStrings;
 
     /**
-     * Constructs a new DateFormatSymbols containing the symbols for the default
-     * Locale.
+     * Constructs a new {@code DateFormatSymbols} instance containing the
+     * symbols for the default locale.
      */
     public DateFormatSymbols() {
         this(Locale.getDefault());
     }
 
     /**
-     * Constructs a new DateFormatSymbols containing the symbols for the
-     * specified Locale.
+     * Constructs a new {@code DateFormatSymbols} instance containing the
+     * symbols for the specified locale.
      * 
      * @param locale
-     *            the Locale
+     *            the locale.
      */
     public DateFormatSymbols(Locale locale) {
         com.ibm.icu.text.DateFormatSymbols icuSymbols = new com.ibm.icu.text.DateFormatSymbols(locale);
@@ -63,14 +96,6 @@
         zoneStrings = icuSymbols.getZoneStrings();
     }
 
-    /**
-     * Answers a new DateFormatSymbols with the same symbols as this
-     * DateFormatSymbols.
-     * 
-     * @return a shallow copy of this DateFormatSymbols
-     * 
-     * @see java.lang.Cloneable
-     */
     @Override
     public Object clone() {
         try {
@@ -92,15 +117,14 @@
     }
 
     /**
-     * Compares the specified object to this DateFormatSymbols and answer if
-     * they are equal. The object must be an instance of DateFormatSymbols with
-     * the same symbols.
+     * Compares this object 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 DateFormatSymbols,
-     *         false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if {@code object} is an instance of
+     *         {@code DateFormatSymbols} and has the same symbols as this
+     *         object, {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -151,87 +175,89 @@
     }
 
     /**
-     * Answers the array of Strings which represent AM and PM. Use the Calendar
-     * constants Calendar.AM and Calendar.PM to index into the array.
+     * Returns the array of strings which represent AM and PM. Use the
+     * {@link java.util.Calendar} constants {@code Calendar.AM} and
+     * {@code Calendar.PM} as indices for the array.
      * 
-     * @return an array of String
+     * @return an array of strings.
      */
     public String[] getAmPmStrings() {
         return ampms.clone();
     }
 
     /**
-     * Answers the array of Strings which represent BC and AD. Use the Calendar
-     * constants GregorianCalendar.BC and GregorianCalendar.AD to index into the
-     * array.
+     * Returns the array of strings which represent BC and AD. Use the
+     * {@link java.util.Calendar} constants {@code GregorianCalendar.BC} and
+     * {@code GregorianCalendar.AD} as indices for the array.
      * 
-     * @return an array of String
+     * @return an array of strings.
      */
     public String[] getEras() {
         return eras.clone();
     }
 
     /**
-     * Answers the pattern characters used by SimpleDateFormat to specify date
-     * and time fields.
+     * Returns the pattern characters used by {@link SimpleDateFormat} to
+     * specify date and time fields.
      * 
-     * @return a String containing the pattern characters
+     * @return a string containing the pattern characters.
      */
     public String getLocalPatternChars() {
         return localPatternChars;
     }
 
     /**
-     * Answers the array of Strings containing the full names of the months. Use
-     * the Calendar constants Calendar.JANUARY, etc. to index into the array.
+     * Returns the array of strings containing the full names of the months. Use
+     * the {@link java.util.Calendar} constants {@code Calendar.JANUARY} etc. as
+     * indices for the array.
      * 
-     * @return an array of String
+     * @return an array of strings.
      */
     public String[] getMonths() {
         return months.clone();
     }
 
     /**
-     * Answers the array of Strings containing the abbreviated names of the
-     * months. Use the Calendar constants Calendar.JANUARY, etc. to index into
-     * the array.
+     * Returns the array of strings containing the abbreviated names of the
+     * months. Use the {@link java.util.Calendar} constants
+     * {@code Calendar.JANUARY} etc. as indices for the array.
      * 
-     * @return an array of String
+     * @return an array of strings.
      */
     public String[] getShortMonths() {
         return shortMonths.clone();
     }
 
     /**
-     * Answers the array of Strings containing the abbreviated names of the days
-     * of the week. Use the Calendar constants Calendar.SUNDAY, etc. to index
-     * into the array.
+     * Returns the array of strings containing the abbreviated names of the days
+     * of the week. Use the {@link java.util.Calendar} constants
+     * {@code Calendar.SUNDAY} etc. as indices for the array.
      * 
-     * @return an array of String
+     * @return an array of strings.
      */
     public String[] getShortWeekdays() {
         return shortWeekdays.clone();
     }
 
     /**
-     * Answers the array of Strings containing the full names of the days of the
-     * week. Use the Calendar constants Calendar.SUNDAY, etc. to index into the
-     * array.
+     * Returns the array of strings containing the full names of the days of the
+     * week. Use the {@link java.util.Calendar} constants
+     * {@code Calendar.SUNDAY} etc. as indices for the array.
      * 
-     * @return an array of String
+     * @return an array of strings.
      */
     public String[] getWeekdays() {
         return weekdays.clone();
     }
 
     /**
-     * Answers the two-dimensional array of Strings containing the names of the
-     * timezones. Each element in the array is an array of five Strings, the
-     * first is a TimeZone ID, and second and third are the full and abbreviated
-     * timezone names for standard time, and the fourth and fifth are the full
+     * Returns the two-dimensional array of strings containing the names of the
+     * time zones. Each element in the array is an array of five strings, the
+     * first is a TimeZone ID, the second and third are the full and abbreviated
+     * time zone names for standard time, and the fourth and fifth are the full
      * and abbreviated names for daylight time.
      * 
-     * @return a two-dimensional array of String
+     * @return a two-dimensional array of strings.
      */
     public String[][] getZoneStrings() {
         String[][] clone = new String[zoneStrings.length][];
@@ -241,14 +267,6 @@
         return clone;
     }
 
-    /**
-     * 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() {
         int hashCode;
@@ -282,37 +300,37 @@
     }
 
     /**
-     * Sets the array of Strings which represent AM and PM. Use the Calendar
-     * constants Calendar.AM and Calendar.PM to index into the array.
+     * Sets the array of strings which represent AM and PM. Use the
+     * {@link java.util.Calendar} constants {@code Calendar.AM} and
+     * {@code Calendar.PM} as indices for the array.
      * 
      * @param data
-     *            the array of Strings
+     *            the array of strings for AM and PM.
      */
     public void setAmPmStrings(String[] data) {
         ampms = data.clone();
     }
 
     /**
-     * Sets the array of Strings which represent BC and AD. Use the Calendar
-     * constants GregorianCalendar.BC and GregorianCalendar.AD to index into the
-     * array.
+     * Sets the array of Strings which represent BC and AD. Use the
+     * {@link java.util.Calendar} constants {@code GregorianCalendar.BC} and
+     * {@code GregorianCalendar.AD} as indices for the array.
      * 
      * @param data
-     *            the array of Strings
+     *            the array of strings for BC and AD.
      */
     public void setEras(String[] data) {
         eras = data.clone();
     }
 
     /**
-     * Sets the pattern characters used by SimpleDateFormat to specify date and
-     * time fields.
+     * Sets the pattern characters used by {@link SimpleDateFormat} to specify
+     * date and time fields.
      * 
      * @param data
-     *            the String containing the pattern characters
-     * 
-     * @exception NullPointerException
-     *                when the data is null
+     *            the string containing the pattern characters.
+     * @throws NullPointerException
+     *            if {@code data} is null
      */
     public void setLocalPatternChars(String data) {
         if (data == null) {
@@ -322,61 +340,62 @@
     }
 
     /**
-     * Sets the array of Strings containing the full names of the months. Use
-     * the Calendar constants Calendar.JANUARY, etc. to index into the array.
+     * Sets the array of strings containing the full names of the months. Use
+     * the {@link java.util.Calendar} constants {@code Calendar.JANUARY} etc. as
+     * indices for the array.
      * 
      * @param data
-     *            the array of Strings
+     *            the array of strings.
      */
     public void setMonths(String[] data) {
         months = data.clone();
     }
 
     /**
-     * Sets the array of Strings containing the abbreviated names of the months.
-     * Use the Calendar constants Calendar.JANUARY, etc. to index into the
-     * array.
+     * Sets the array of strings containing the abbreviated names of the months.
+     * Use the {@link java.util.Calendar} constants {@code Calendar.JANUARY}
+     * etc. as indices for the array.
      * 
      * @param data
-     *            the array of Strings
+     *            the array of strings.
      */
     public void setShortMonths(String[] data) {
         shortMonths = data.clone();
     }
 
     /**
-     * Sets the array of Strings containing the abbreviated names of the days of
-     * the week. Use the Calendar constants Calendar.SUNDAY, etc. to index into
-     * the array.
+     * Sets the array of strings containing the abbreviated names of the days of
+     * the week. Use the {@link java.util.Calendar} constants
+     * {@code Calendar.SUNDAY} etc. as indices for the array.
      * 
      * @param data
-     *            the array of Strings
+     *            the array of strings.
      */
     public void setShortWeekdays(String[] data) {
         shortWeekdays = data.clone();
     }
 
     /**
-     * Sets the array of Strings containing the full names of the days of the
-     * week. Use the Calendar constants Calendar.SUNDAY, etc. to index into the
-     * array.
+     * Sets the array of strings containing the full names of the days of the
+     * week. Use the {@link java.util.Calendar} constants
+     * {@code Calendar.SUNDAY} etc. as indices for the array.
      * 
      * @param data
-     *            the array of Strings
+     *            the array of strings.
      */
     public void setWeekdays(String[] data) {
         weekdays = data.clone();
     }
 
     /**
-     * Sets the two-dimensional array of Strings containing the names of the
-     * timezones. Each element in the array is an array of five Strings, the
+     * Sets the two-dimensional array of strings containing the names of the
+     * time zones. Each element in the array is an array of five strings, the
      * first is a TimeZone ID, and second and third are the full and abbreviated
-     * timezone names for standard time, and the fourth and fifth are the full
+     * time zone names for standard time, and the fourth and fifth are the full
      * and abbreviated names for daylight time.
      * 
      * @param data
-     *            the two-dimensional array of Strings
+     *            the two-dimensional array of strings.
      */
     public void setZoneStrings(String[][] data) {
         zoneStrings = data.clone();

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java Thu May  7 08:42:00 2009
@@ -29,9 +29,512 @@
 import java.util.Locale;
 
 /**
- * DecimalFormat is used to format and parse numbers, both integers and
- * fractions, based on a pattern. The pattern characters used can be either
- * localized or non-localized.
+ * A concrete subclass of {@link NumberFormat} that formats decimal numbers. It
+ * has a variety of features designed to make it possible to parse and format
+ * numbers in any locale, including support for Western, Arabic, or Indic
+ * digits. It also supports different flavors of numbers, including integers
+ * ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"),
+ * percentages ("12%"), and currency amounts ("$123"). All of these flavors can
+ * be easily localized.
+ * <p>
+ * <strong>This is an enhanced version of {@code DecimalFormat} that is based on
+ * the standard version in the RI. New or changed functionality is labeled
+ * <strong><font color="red">NEW</font></strong>.</strong>
+ * <p>
+ * To obtain a {@link NumberFormat} for a specific locale (including the default
+ * locale), call one of {@code NumberFormat}'s factory methods such as
+ * {@code NumberFormat.getInstance}. Do not call the {@code DecimalFormat}
+ * constructors directly, unless you know what you are doing, since the
+ * {@link NumberFormat} factory methods may return subclasses other than
+ * {@code DecimalFormat}. If you need to customize the format object, do
+ * something like this: <blockquote>
+ *
+ * <pre>
+ * NumberFormat f = NumberFormat.getInstance(loc);
+ * if (f instanceof DecimalFormat) {
+ *     ((DecimalFormat)f).setDecimalSeparatorAlwaysShown(true);
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <h5>Example:</h5>
+ * <blockquote>
+ *
+ * <pre>
+ * // Print out a number using the localized number, currency,
+ * // and percent format for each locale
+ * Locale[] locales = NumberFormat.getAvailableLocales();
+ * double myNumber = -1234.56;
+ * NumberFormat format;
+ * for (int j = 0; j &lt; 3; ++j) {
+ *     System.out.println(&quot;FORMAT&quot;);
+ *     for (int i = 0; i &lt; locales.length; ++i) {
+ *         if (locales[i].getCountry().length() == 0) {
+ *             // Skip language-only locales
+ *             continue;
+ *         }
+ *         System.out.print(locales[i].getDisplayName());
+ *         switch (j) {
+ *             case 0:
+ *                 format = NumberFormat.getInstance(locales[i]);
+ *                 break;
+ *             case 1:
+ *                 format = NumberFormat.getCurrencyInstance(locales[i]);
+ *                 break;
+ *             default:
+ *                 format = NumberFormat.getPercentInstance(locales[i]);
+ *                 break;
+ *         }
+ *         try {
+ *             // Assume format is a DecimalFormat
+ *             System.out.print(&quot;: &quot;; + ((DecimalFormat)format).toPattern() + &quot; -&gt; &quot;
+ *                     + form.format(myNumber));
+ *         } catch (Exception e) {
+ *         }
+ *         try {
+ *             System.out.println(&quot; -&gt; &quot; + format.parse(form.format(myNumber)));
+ *         } catch (ParseException e) {
+ *         }
+ *     }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <h4>Patterns</h4>
+ * <p>
+ * A {@code DecimalFormat} consists of a <em>pattern</em> and a set of
+ * <em>symbols</em>. The pattern may be set directly using
+ * {@link #applyPattern(String)}, or indirectly using other API methods which
+ * manipulate aspects of the pattern, such as the minimum number of integer
+ * digits. The symbols are stored in a {@link DecimalFormatSymbols} object. When
+ * using the {@link NumberFormat} factory methods, the pattern and symbols are
+ * read from ICU's locale data.
+ * <h4>Special Pattern Characters</h4>
+ * <p>
+ * Many characters in a pattern are taken literally; they are matched during
+ * parsing and are written out unchanged during formatting. On the other hand,
+ * special characters stand for other characters, strings, or classes of
+ * characters. For example, the '#' character is replaced by a localized digit.
+ * Often the replacement character is the same as the pattern character; in the
+ * U.S. locale, the ',' grouping character is replaced by ','. However, the
+ * replacement is still happening, and if the symbols are modified, the grouping
+ * character changes. Some special characters affect the behavior of the
+ * formatter by their presence; for example, if the percent character is seen,
+ * then the value is multiplied by 100 before being displayed.
+ * <p>
+ * To insert a special character in a pattern as a literal, that is, without any
+ * special meaning, the character must be quoted. There are some exceptions to
+ * this which are noted below.
+ * <p>
+ * The characters listed here are used in non-localized patterns. Localized
+ * patterns use the corresponding characters taken from this formatter's
+ * {@link DecimalFormatSymbols} object instead, and these characters lose their
+ * special status. Two exceptions are the currency sign and quote, which are not
+ * localized.
+ * <blockquote> <table border="0" cellspacing="3" cellpadding="0" summary="Chart
+ * showing symbol, location, localized, and meaning.">
+ * <tr bgcolor="#ccccff">
+ * <th align="left">Symbol</th>
+ * <th align="left">Location</th>
+ * <th align="left">Localized?</th>
+ * <th align="left">Meaning</th>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code 0}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Digit.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code @}</td>
+ * <td>Number</td>
+ * <td>No</td>
+ * <td><strong><font color="red">NEW</font>&nbsp;</strong> Significant
+ * digit.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code #}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Digit, leading zeroes are not shown.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code .}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Decimal separator or monetary decimal separator.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code -}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Minus sign.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code ,}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Grouping separator.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code E}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Separates mantissa and exponent in scientific notation.
+ * <em>Does not need to be quoted in prefix or suffix.</em></td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code +}</td>
+ * <td>Exponent</td>
+ * <td>Yes</td>
+ * <td><strong><font color="red">NEW</font>&nbsp;</strong> Prefix
+ * positive exponents with localized plus sign.
+ * <em>Does not need to be quoted in prefix or suffix.</em></td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code ;}</td>
+ * <td>Subpattern boundary</td>
+ * <td>Yes</td>
+ * <td>Separates positive and negative subpatterns.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code %}</td>
+ * <td>Prefix or suffix</td>
+ * <td>Yes</td>
+ * <td>Multiply by 100 and show as percentage.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code \u2030} ({@code &#92;u2030})</td>
+ * <td>Prefix or suffix</td>
+ * <td>Yes</td>
+ * <td>Multiply by 1000 and show as per mille.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code &#164;} ({@code &#92;u00A4})</td>
+ * <td>Prefix or suffix</td>
+ * <td>No</td>
+ * <td>Currency sign, replaced by currency symbol. If doubled, replaced by
+ * international currency symbol. If present in a pattern, the monetary decimal
+ * separator is used instead of the decimal separator.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code '}</td>
+ * <td>Prefix or suffix</td>
+ * <td>No</td>
+ * <td>Used to quote special characters in a prefix or suffix, for example,
+ * {@code "'#'#"} formats 123 to {@code "#123"}. To create a single quote
+ * itself, use two in a row: {@code "# o''clock"}.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code *}</td>
+ * <td>Prefix or suffix boundary</td>
+ * <td>Yes</td>
+ * <td><strong><font color="red">NEW</font>&nbsp;</strong> Pad escape,
+ * precedes pad character. </td>
+ * </tr>
+ * </table> </blockquote>
+ * <p>
+ * A {@code DecimalFormat} pattern contains a postive and negative subpattern,
+ * for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric
+ * part and a suffix. If there is no explicit negative subpattern, the negative
+ * subpattern is the localized minus sign prefixed to the positive subpattern.
+ * That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit
+ * negative subpattern, it serves only to specify the negative prefix and
+ * suffix; the number of digits, minimal digits, and other characteristics are
+ * ignored in the negative subpattern. This means that "#,##0.0#;(#)" produces
+ * precisely the same result as "#,##0.0#;(#,##0.0#)".
+ * <p>
+ * The prefixes, suffixes, and various symbols used for infinity, digits,
+ * thousands separators, decimal separators, etc. may be set to arbitrary
+ * values, and they will appear properly during formatting. However, care must
+ * be taken that the symbols and strings do not conflict, or parsing will be
+ * unreliable. For example, either the positive and negative prefixes or the
+ * suffixes must be distinct for {@link #parse} to be able to distinguish
+ * positive from negative values. Another example is that the decimal separator
+ * and thousands separator should be distinct characters, or parsing will be
+ * impossible.
+ * <p>
+ * The <em>grouping separator</em> is a character that separates clusters of
+ * integer digits to make large numbers more legible. It is commonly used for
+ * thousands, but in some locales it separates ten-thousands. The <em>grouping
+ * size</em>
+ * is the number of digits between the grouping separators, such as 3 for
+ * "100,000,000" or 4 for "1 0000 0000". There are actually two different
+ * grouping sizes: One used for the least significant integer digits, the
+ * <em>primary grouping size</em>, and one used for all others, the
+ * <em>secondary grouping size</em>. In most locales these are the same, but
+ * sometimes they are different. For example, if the primary grouping interval
+ * is 3, and the secondary is 2, then this corresponds to the pattern
+ * "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a
+ * pattern contains multiple grouping separators, the interval between the last
+ * one and the end of the integer defines the primary grouping size, and the
+ * interval between the last two defines the secondary grouping size. All others
+ * are ignored, so "#,##,###,####", "###,###,####" and "##,#,###,####" produce
+ * the same result.
+ * <p>
+ * Illegal patterns, such as "#.#.#" or "#.###,###", will cause
+ * {@code DecimalFormat} to throw an {@link IllegalArgumentException} with a
+ * message that describes the problem.
+ * <h4>Pattern BNF</h4>
+ *
+ * <pre>
+ * pattern    := subpattern (';' subpattern)?
+ * subpattern := prefix? number exponent? suffix?
+ * number     := (integer ('.' fraction)?) | sigDigits
+ * prefix     := '\\u0000'..'\\uFFFD' - specialCharacters
+ * suffix     := '\\u0000'..'\\uFFFD' - specialCharacters
+ * integer    := '#'* '0'* '0'
+ * fraction   := '0'* '#'*
+ * sigDigits  := '#'* '@' '@'* '#'*
+ * exponent   := 'E' '+'? '0'* '0'
+ * padSpec    := '*' padChar
+ * padChar    := '\\u0000'..'\\uFFFD' - quote
+ *
+ * Notation:
+ *   X*       0 or more instances of X
+ *   X?       0 or 1 instances of X
+ *   X|Y      either X or Y
+ *   C..D     any character from C up to D, inclusive
+ *   S-T      characters in S, except those in T
+ * </pre>
+ *
+ * The first subpattern is for positive numbers. The second (optional)
+ * subpattern is for negative numbers.
+ * <p>
+ * Not indicated in the BNF syntax above:
+ * <ul>
+ * <li>The grouping separator ',' can occur inside the integer and sigDigits
+ * elements, between any two pattern characters of that element, as long as the
+ * integer or sigDigits element is not followed by the exponent element.
+ * <li><font color="red"><strong>NEW</strong>&nbsp;</font> Two
+ * grouping intervals are recognized: The one between the decimal point and the
+ * first grouping symbol and the one between the first and second grouping
+ * symbols. These intervals are identical in most locales, but in some locales
+ * they differ. For example, the pattern &quot;#,##,###&quot; formats the number
+ * 123456789 as &quot;12,34,56,789&quot;.</li>
+ * <li> <strong><font color="red">NEW</font>&nbsp;</strong> The pad
+ * specifier {@code padSpec} may appear before the prefix, after the prefix,
+ * before the suffix, after the suffix or not at all.
+ * </ul>
+ * <h4>Parsing</h4>
+ * <p>
+ * {@code DecimalFormat} parses all Unicode characters that represent decimal
+ * digits, as defined by {@link Character#digit(int, int)}. In addition,
+ * {@code DecimalFormat} also recognizes as digits the ten consecutive
+ * characters starting with the localized zero digit defined in the
+ * {@link DecimalFormatSymbols} object. During formatting, the
+ * {@link DecimalFormatSymbols}-based digits are written out.
+ * <p>
+ * During parsing, grouping separators are ignored.
+ * <p>
+ * If {@link #parse(String, ParsePosition)} fails to parse a string, it returns
+ * {@code null} and leaves the parse position unchanged.
+ * <h4>Formatting</h4>
+ * <p>
+ * Formatting is guided by several parameters, all of which can be specified
+ * either using a pattern or using the API. The following description applies to
+ * formats that do not use <a href="#sci">scientific notation</a> or <a
+ * href="#sigdig">significant digits</a>.
+ * <ul>
+ * <li>If the number of actual integer digits exceeds the
+ * <em>maximum integer digits</em>, then only the least significant digits
+ * are shown. For example, 1997 is formatted as "97" if maximum integer digits
+ * is set to 2.
+ * <li>If the number of actual integer digits is less than the
+ * <em>minimum integer digits</em>, then leading zeros are added. For
+ * example, 1997 is formatted as "01997" if minimum integer digits is set to 5.
+ * <li>If the number of actual fraction digits exceeds the <em>maximum
+ * fraction digits</em>,
+ * then half-even rounding is performed to the maximum fraction digits. For
+ * example, 0.125 is formatted as "0.12" if the maximum fraction digits is 2.
+ * <li>If the number of actual fraction digits is less than the
+ * <em>minimum fraction digits</em>, then trailing zeros are added. For
+ * example, 0.125 is formatted as "0.1250" if the mimimum fraction digits is set
+ * to 4.
+ * <li>Trailing fractional zeros are not displayed if they occur <em>j</em>
+ * positions after the decimal, where <em>j</em> is less than the maximum
+ * fraction digits. For example, 0.10004 is formatted as "0.1" if the maximum
+ * fraction digits is four or less.
+ * </ul>
+ * <p>
+ * <strong>Special Values</strong>
+ * <p>
+ * {@code NaN} is represented as a single character, typically
+ * {@code &#92;uFFFD}. This character is determined by the
+ * {@link DecimalFormatSymbols} object. This is the only value for which the
+ * prefixes and suffixes are not used.
+ * <p>
+ * Infinity is represented as a single character, typically {@code &#92;u221E},
+ * with the positive or negative prefixes and suffixes applied. The infinity
+ * character is determined by the {@link DecimalFormatSymbols} object. <a
+ * name="sci">
+ * <h4>Scientific Notation</h4>
+ * </a>
+ * <p>
+ * Numbers in scientific notation are expressed as the product of a mantissa and
+ * a power of ten, for example, 1234 can be expressed as 1.234 x 10<sup>3</sup>.
+ * The mantissa is typically in the half-open interval [1.0, 10.0) or sometimes
+ * [0.0, 1.0), but it does not need to be. {@code DecimalFormat} supports
+ * arbitrary mantissas. {@code DecimalFormat} can be instructed to use
+ * scientific notation through the API or through the pattern. In a pattern, the
+ * exponent character immediately followed by one or more digit characters
+ * indicates scientific notation. Example: "0.###E0" formats the number 1234 as
+ * "1.234E3".
+ * <ul>
+ * <li>The number of digit characters after the exponent character gives the
+ * minimum exponent digit count. There is no maximum. Negative exponents are
+ * formatted using the localized minus sign, <em>not</em> the prefix and
+ * suffix from the pattern. This allows patterns such as "0.###E0 m/s". To
+ * prefix positive exponents with a localized plus sign, specify '+' between the
+ * exponent and the digits: "0.###E+0" will produce formats "1E+1", "1E+0",
+ * "1E-1", etc. (In localized patterns, use the localized plus sign rather than
+ * '+'.)
+ * <li>The minimum number of integer digits is achieved by adjusting the
+ * exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". This
+ * only happens if there is no maximum number of integer digits. If there is a
+ * maximum, then the minimum number of integer digits is fixed at one.
+ * <li>The maximum number of integer digits, if present, specifies the exponent
+ * grouping. The most common use of this is to generate <em>engineering
+ * notation</em>,
+ * in which the exponent is a multiple of three, e.g., "##0.###E0". The number
+ * 12345 is formatted using "##0.###E0" as "12.345E3".
+ * <li>When using scientific notation, the formatter controls the digit counts
+ * using significant digits logic. The maximum number of significant digits
+ * limits the total number of integer and fraction digits that will be shown in
+ * the mantissa; it does not affect parsing. For example, 12345 formatted with
+ * "##0.##E0" is "12.3E3". See the section on significant digits for more
+ * details.
+ * <li>The number of significant digits shown is determined as follows: If no
+ * significant digits are used in the pattern then the minimum number of
+ * significant digits shown is one, the maximum number of significant digits
+ * shown is the sum of the <em>minimum integer</em> and
+ * <em>maximum fraction</em> digits, and it is unaffected by the maximum
+ * integer digits. If this sum is zero, then all significant digits are shown.
+ * If significant digits are used in the pattern then the number of integer
+ * digits is fixed at one and there is no exponent grouping.
+ * <li>Exponential patterns may not contain grouping separators.
+ * </ul>
+ * <a name="sigdig">
+ * <h4> <strong><font color="red">NEW</font>&nbsp;</strong> Significant
+ * Digits</h4>
+ * <p>
+ * </a> {@code DecimalFormat} has two ways of controlling how many digits are
+ * shown: (a) significant digit counts or (b) integer and fraction digit counts.
+ * Integer and fraction digit counts are described above. When a formatter uses
+ * significant digits counts, the number of integer and fraction digits is not
+ * specified directly, and the formatter settings for these counts are ignored.
+ * Instead, the formatter uses as many integer and fraction digits as required
+ * to display the specified number of significant digits.
+ * <h5>Examples:</h5>
+ * <blockquote> <table border=0 cellspacing=3 cellpadding=0>
+ * <tr bgcolor="#ccccff">
+ * <th align="left">Pattern</th>
+ * <th align="left">Minimum significant digits</th>
+ * <th align="left">Maximum significant digits</th>
+ * <th align="left">Number</th>
+ * <th align="left">Output of format()</th>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code @@@}
+ * <td>3</td>
+ * <td>3</td>
+ * <td>12345</td>
+ * <td>{@code 12300}</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code @@@}</td>
+ * <td>3</td>
+ * <td>3</td>
+ * <td>0.12345</td>
+ * <td>{@code 0.123}</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code @@##}</td>
+ * <td>2</td>
+ * <td>4</td>
+ * <td>3.14159</td>
+ * <td>{@code 3.142}</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code @@##}</td>
+ * <td>2</td>
+ * <td>4</td>
+ * <td>1.23004</td>
+ * <td>{@code 1.23}</td>
+ * </tr>
+ * </table> </blockquote>
+ * <ul>
+ * <li>Significant digit counts may be expressed using patterns that specify a
+ * minimum and maximum number of significant digits. These are indicated by the
+ * {@code '@'} and {@code '#'} characters. The minimum number of significant
+ * digits is the number of {@code '@'} characters. The maximum number of
+ * significant digits is the number of {@code '@'} characters plus the number of
+ * {@code '#'} characters following on the right. For example, the pattern
+ * {@code "@@@"} indicates exactly 3 significant digits. The pattern
+ * {@code "@##"} indicates from 1 to 3 significant digits. Trailing zero digits
+ * to the right of the decimal separator are suppressed after the minimum number
+ * of significant digits have been shown. For example, the pattern {@code "@##"}
+ * formats the number 0.1203 as {@code "0.12"}.
+ * <li>If a pattern uses significant digits, it may not contain a decimal
+ * separator, nor the {@code '0'} pattern character. Patterns such as
+ * {@code "@00"} or {@code "@.###"} are disallowed.
+ * <li>Any number of {@code '#'} characters may be prepended to the left of the
+ * leftmost {@code '@'} character. These have no effect on the minimum and
+ * maximum significant digit counts, but may be used to position grouping
+ * separators. For example, {@code "#,#@#"} indicates a minimum of one
+ * significant digit, a maximum of two significant digits, and a grouping size
+ * of three.
+ * <li>In order to enable significant digits formatting, use a pattern
+ * containing the {@code '@'} pattern character.
+ * <li>In order to disable significant digits formatting, use a pattern that
+ * does not contain the {@code '@'} pattern character.
+ * <li>The number of significant digits has no effect on parsing.
+ * <li>Significant digits may be used together with exponential notation. Such
+ * patterns are equivalent to a normal exponential pattern with a minimum and
+ * maximum integer digit count of one, a minimum fraction digit count of the
+ * number of '@' characters in the pattern - 1, and a maximum fraction digit
+ * count of the number of '@' and '#' characters in the pattern - 1. For
+ * example, the pattern {@code "@@###E0"} is equivalent to {@code "0.0###E0"}.
+ * <li>If signficant digits are in use then the integer and fraction digit
+ * counts, as set via the API, are ignored.
+ * </ul>
+ * <h4> <strong><font color="red">NEW</font>&nbsp;</strong> Padding</h4>
+ * <p>
+ * {@code DecimalFormat} supports padding the result of {@code format} to a
+ * specific width. Padding may be specified either through the API or through
+ * the pattern syntax. In a pattern, the pad escape character followed by a
+ * single pad character causes padding to be parsed and formatted. The pad
+ * escape character is '*' in unlocalized patterns. For example,
+ * {@code "$*x#,##0.00"} formats 123 to {@code "$xx123.00"}, and 1234 to
+ * {@code "$1,234.00"}.
+ * <ul>
+ * <li>When padding is in effect, the width of the positive subpattern,
+ * including prefix and suffix, determines the format width. For example, in the
+ * pattern {@code "* #0 o''clock"}, the format width is 10.</li>
+ * <li>The width is counted in 16-bit code units (Java {@code char}s).</li>
+ * <li>Some parameters which usually do not matter have meaning when padding is
+ * used, because the pattern width is significant with padding. In the pattern "*
+ * ##,##,#,##0.##", the format width is 14. The initial characters "##,##," do
+ * not affect the grouping size or maximum integer digits, but they do affect
+ * the format width.</li>
+ * <li>Padding may be inserted at one of four locations: before the prefix,
+ * after the prefix, before the suffix or after the suffix. If padding is
+ * specified in any other location, {@link #applyPattern} throws an {@link
+ * IllegalArgumentException}. If there is no prefix, before the prefix and after
+ * the prefix are equivalent, likewise for the suffix.</li>
+ * <li>When specified in a pattern, the 16-bit {@code char} immediately
+ * following the pad escape is the pad character. This may be any character,
+ * including a special pattern character. That is, the pad escape
+ * <em>escapes</em> the following character. If there is no character after
+ * the pad escape, then the pattern is illegal.</li>
+ * </ul>
+ * <h4>Synchronization</h4>
+ * <p>
+ * {@code DecimalFormat} objects are not synchronized. Multiple threads should
+ * not access one formatter concurrently.
+ *
+ * @see Format
+ * @see NumberFormat
  */
 public class DecimalFormat extends NumberFormat {
 
@@ -50,8 +553,8 @@
     private transient int serialVersionOnStream = 3;
 
     /**
-     * Constructs a new DecimalFormat for formatting and parsing numbers for the
-     * default Locale.
+     * Constructs a new {@code DecimalFormat} for formatting and parsing numbers
+     * for the default locale.
      */
     public DecimalFormat() {
         Locale locale = Locale.getDefault();
@@ -66,14 +569,13 @@
     }
 
     /**
-     * Constructs a new DecimalFormat using the specified non-localized pattern
-     * and the DecimalFormatSymbols for the default Locale.
+     * Constructs a new {@code DecimalFormat} using the specified non-localized
+     * pattern and the {@code DecimalFormatSymbols} for the default Locale.
      * 
      * @param pattern
-     *            the non-localized pattern
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the non-localized pattern.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public DecimalFormat(String pattern) {
         Locale locale = Locale.getDefault();
@@ -88,16 +590,15 @@
     }
 
     /**
-     * Constructs a new DecimalFormat using the specified non-localized pattern
-     * and DecimalFormatSymbols.
+     * Constructs a new {@code DecimalFormat} using the specified non-localized
+     * pattern and {@code DecimalFormatSymbols}.
      * 
      * @param pattern
-     *            the non-localized pattern
+     *            the non-localized pattern.
      * @param value
-     *            the DecimalFormatSymbols
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the DecimalFormatSymbols.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public DecimalFormat(String pattern, DecimalFormatSymbols value) {
         symbols = (DecimalFormatSymbols) value.clone();
@@ -114,28 +615,26 @@
     }
 
     /**
-     * Changes the pattern of this DecimalFormat to the specified pattern which
+     * Changes the pattern of this decimal format to the specified pattern which
      * uses localized pattern characters.
      * 
      * @param pattern
-     *            the localized pattern
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the localized pattern.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public void applyLocalizedPattern(String pattern) {
         dform.applyLocalizedPattern(pattern);
     }
 
     /**
-     * Changes the pattern of this SimpleDateFormat to the specified pattern
-     * which uses non-localized pattern characters.
+     * Changes the pattern of this decimal format to the specified pattern which
+     * uses non-localized pattern characters.
      * 
      * @param pattern
-     *            the non-localized pattern
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the non-localized pattern.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public void applyPattern(String pattern) {
 
@@ -143,11 +642,10 @@
     }
 
     /**
-     * Answers a new instance of DecimalFormat with the same pattern and
-     * properties as this DecimalFormat.
-     * 
-     * @return a shallow copy of this DecimalFormat
+     * Returns a new instance of {@code DecimalFormat} with the same pattern and
+     * properties as this decimal format.
      * 
+     * @return a shallow copy of this decimal format.
      * @see java.lang.Cloneable
      */
     @Override
@@ -159,15 +657,14 @@
     }
 
     /**
-     * Compares the specified object to this DecimalFormat and answer if they
-     * are equal. The object must be an instance of DecimalFormat with the same
-     * pattern and properties.
+     * Compares the specified object to this decimal format and indicates if
+     * they are equal. In order to be equal, {@code object} must be an instance
+     * of {@code DecimalFormat} with the same pattern and properties.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this DecimalFormat,
-     *         false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this decimal
+     *         format; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -184,19 +681,18 @@
     }
 
     /**
-     * Formats the specified object using the rules of this DecimalNumberFormat
-     * and returns an AttributedCharacterIterator with the formatted number and
-     * attributes.
+     * Formats the specified object using the rules of this decimal format and
+     * returns an {@code AttributedCharacterIterator} with the formatted number
+     * and attributes.
      * 
      * @param object
-     *            the object to format
+     *            the object to format.
      * @return an AttributedCharacterIterator with the formatted number and
-     *         attributes
-     * 
-     * @exception NullPointerException
-     *                when the object is null
-     * @exception IllegalArgumentException
-     *                when the object cannot be formatted by this Format
+     *         attributes.
+     * @throws IllegalArgumentException
+     *             if {@code object} cannot be formatted by this format.
+     * @throws NullPointerException
+     *             if {@code object} is {@code null}.
      */
     @Override
     public AttributedCharacterIterator formatToCharacterIterator(Object object) {
@@ -207,18 +703,23 @@
     }
 
     /**
-     * Formats the double value into the specified StringBuffer using the
-     * pattern of this DecimalFormat. 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 double value as a string using the pattern of this
+     * decimal format and appends the string to the specified string buffer.
+     * <p>
+     * If the {@code field} member of {@code position} 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 value
-     *            the double to format
+     *            the double to format.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted double value
+     *            to.
      * @param position
-     *            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.
      */
     @Override
     public StringBuffer format(double value, StringBuffer buffer,
@@ -227,18 +728,23 @@
     }
 
     /**
-     * Formats the long value into the specified StringBuffer using the pattern
-     * of this DecimalFormat. 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 long value as a string using the pattern of this
+     * decimal format and appends the string to the specified string buffer.
+     * <p>
+     * If the {@code field} member of {@code position} 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 value
-     *            the long to format
+     *            the long to format.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted long value
+     *            to.
      * @param position
-     *            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.
      */
     @Override
     public StringBuffer format(long value, StringBuffer buffer,
@@ -247,20 +753,26 @@
     }
 
     /**
-     * Formats the number into the specified StringBuffer using the pattern of
-     * this DecimalFormat. 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
+     * decimal format and appends the string to the specified string buffer.
+     * <p>
+     * If the {@code field} member of {@code position} 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 number
-     *            the object to format
+     *            the object to format.
      * @param toAppendTo
-     *            the StringBuffer
+     *            the target string buffer to append the formatted number to.
      * @param pos
-     *            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.
      * @throws IllegalArgumentException
-     *             if the given number is not instance of <code>Number</code>
+     *             if {@code number} is not an instance of {@code Number}.
+     * @throws NullPointerException
+     *             if {@code toAppendTo} or {@code pos} is {@code null}.
      */
     @Override
     public final StringBuffer format(Object number, StringBuffer toAppendTo,
@@ -278,18 +790,19 @@
     }
 
     /**
-     * Answers the DecimalFormatSymbols used by this DecimalFormat.
+     * Returns the {@code DecimalFormatSymbols} used by this decimal format.
      * 
-     * @return a DecimalFormatSymbols
+     * @return a copy of the {@code DecimalFormatSymbols} used by this decimal
+     *         format.
      */
     public DecimalFormatSymbols getDecimalFormatSymbols() {
         return (DecimalFormatSymbols) symbols.clone();
     }
 
     /**
-     * Answers the currency used by this decimal format.
+     * Returns the currency used by this decimal format.
      * 
-     * @return currency of DecimalFormatSymbols used by this decimal format
+     * @return the currency used by this decimal format.
      * @see DecimalFormatSymbols#getCurrency()
      */
     @Override
@@ -301,120 +814,118 @@
     }
 
     /**
-     * Answers the number of digits grouped together by the grouping separator.
-     * 
-     * @return the number of digits grouped together
+     * Returns the number of digits grouped together by the grouping separator.
+     * This only allows to get the primary grouping size. There is no API to get
+     * the secondary grouping size.
+     *
+     * @return the number of digits grouped together.
      */
     public int getGroupingSize() {
         return dform.getGroupingSize();
     }
 
     /**
-     * Answers the multiplier which is applied to the number before formatting
+     * Returns the multiplier which is applied to the number before formatting
      * or after parsing.
      * 
-     * @return the multiplier
+     * @return the multiplier.
      */
     public int getMultiplier() {
         return dform.getMultiplier();
     }
 
     /**
-     * Answers the prefix which is formatted or parsed before a negative number.
+     * Returns the prefix which is formatted or parsed before a negative number.
      * 
-     * @return the negative prefix
+     * @return the negative prefix.
      */
     public String getNegativePrefix() {
         return dform.getNegativePrefix();
     }
 
     /**
-     * Answers the suffix which is formatted or parsed after a negative number.
+     * Returns the suffix which is formatted or parsed after a negative number.
      * 
-     * @return the negative suffix
+     * @return the negative suffix.
      */
     public String getNegativeSuffix() {
         return dform.getNegativeSuffix();
     }
 
     /**
-     * Answers the prefix which is formatted or parsed before a positive number.
+     * Returns the prefix which is formatted or parsed before a positive number.
      * 
-     * @return the positive prefix
+     * @return the positive prefix.
      */
     public String getPositivePrefix() {
         return dform.getPositivePrefix();
     }
 
     /**
-     * Answers the suffix which is formatted or parsed after a positive number.
+     * Returns the suffix which is formatted or parsed after a positive number.
      * 
-     * @return the positive suffix
+     * @return the positive suffix.
      */
     public String getPositiveSuffix() {
         return dform.getPositiveSuffix();
     }
 
-    /**
-     * 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 dform.hashCode();
     }
 
     /**
-     * Answers whether the decimal separator is shown when there are no
+     * Indicates whether the decimal separator is shown when there are no
      * fractional digits.
      * 
-     * @return true if the decimal separator should always be formatted, false
-     *         otherwise
+     * @return {@code true} if the decimal separator should always be formatted;
+     *         {@code false} otherwise.
      */
     public boolean isDecimalSeparatorAlwaysShown() {
         return dform.isDecimalSeparatorAlwaysShown();
     }
 
     /**
-     * This value indicates whether the return object of the parse operation
-     * will be of type BigDecimal. This value will default to false.
+     * This value indicates whether the return object of the parse operation is
+     * of type {@code BigDecimal}. This value defaults to {@code false}.
      * 
-     * @return true and parse will always return BigDecimals, false and the type
-     *         of the result will be Long or Double.
+     * @return {@code true} if parse always returns {@code BigDecimals},
+     *         {@code false} if the type of the result is {@code Long} or
+     *         {@code Double}.
      */
     public boolean isParseBigDecimal() {
         return this.parseBigDecimal;
     }
 
     /**
-     * When DecimalFormat is used to parsing, and this value is set to true,
-     * then all the resulting number will be of type
-     * <code>java.lang.Integer</code>. Except that, NaN, positive and
-     * negative infinity are still returned as <code>java.lang.Double</code>
-     * 
-     * In this implementation, com.ibm.icu.text.DecimalFormat is wrapped to
-     * fulfill most of the format and parse feature. And this method is
-     * delegated to the wrapped instance of com.ibm.icu.text.DecimalFormat.
+     * Sets the flag that indicates whether numbers will be parsed as integers.
+     * When this decimal format is used for parsing and this value is set to
+     * {@code true}, then the resulting numbers will be of type
+     * {@code java.lang.Integer}. Special cases are NaN, positive and negative
+     * infinity, which are still returned as {@code java.lang.Double}.
      * 
+     *
      * @param value
-     *            If set to true, all the resulting number will be of type
-     *            java.lang.Integer except some special cases.
+     *            {@code true} that the resulting numbers of parse operations
+     *            will be of type {@code java.lang.Integer} except for the
+     *            special cases described above.
      */
     @Override
     public void setParseIntegerOnly(boolean value) {
+        // In this implementation, com.ibm.icu.text.DecimalFormat is wrapped to
+        // fulfill most of the format and parse feature. And this method is
+        // delegated to the wrapped instance of com.ibm.icu.text.DecimalFormat.
+
         dform.setParseIntegerOnly(value);
     }
 
     /**
-     * Returns true if this <code>DecimalFormat</code>'s all resulting number
-     * will be of type <code>java.lang.Integer</code>
+     * Indicates whether parsing with this decimal format will only
+     * return numbers of type {@code java.lang.Integer}.
      * 
-     * @return true if this <code>DecimalFormat</code>'s all resulting number
-     *         will be of type <code>java.lang.Integer</code>
+     * @return {@code true} if this {@code DecimalFormat}'s parse method only
+     *         returns {@code java.lang.Integer}; {@code false} otherwise.
      */
     @Override
     public boolean isParseIntegerOnly() {
@@ -424,20 +935,27 @@
     private static final Double NEGATIVE_ZERO_DOUBLE = new Double(-0.0);
 
     /**
-     * Parse a Long or Double 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 {@code Long} or {@code Double} 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.
      * 
      * @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 a Long or Double resulting from the parse, or null if there is an
-     *         error. The result will be a Long if the parsed number is an
-     *         integer in the range of a long, otherwise the result is a Double.
+     *            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 a {@code Long} or {@code Double} resulting from the parse or
+     *         {@code null} if there is an error. The result will be a
+     *         {@code Long} if the parsed number is an integer in the range of a
+     *         long, otherwise the result is a {@code Double}. If
+     *         {@code isParseBigDecimal} is {@code true} then it returns the
+     *         result as a {@code BigDecimal}.
      */
     @Override
     public Number parse(String string, ParsePosition position) {
@@ -475,10 +993,10 @@
     }
 
     /**
-     * Sets the DecimalFormatSymbols used by this DecimalFormat.
+     * Sets the {@code DecimalFormatSymbols} used by this decimal format.
      * 
      * @param value
-     *            the DecimalFormatSymbols
+     *            the {@code DecimalFormatSymbols} to set.
      */
     public void setDecimalFormatSymbols(DecimalFormatSymbols value) {
         if (value != null) {
@@ -494,6 +1012,7 @@
      * digits remain the same.
      * 
      * @param currency
+     *            the currency this {@code DecimalFormat} should use.
      * @see DecimalFormatSymbols#setCurrency(Currency)
      */
     @Override
@@ -508,8 +1027,8 @@
      * digits.
      * 
      * @param value
-     *            true if the decimal separator should always be formatted,
-     *            false otherwise
+     *            {@code true} if the decimal separator should always be
+     *            formatted; {@code false} otherwise.
      */
     public void setDecimalSeparatorAlwaysShown(boolean value) {
         dform.setDecimalSeparatorAlwaysShown(value);
@@ -517,9 +1036,11 @@
 
     /**
      * Sets the number of digits grouped together by the grouping separator.
-     * 
+     * This only allows to set the primary grouping size; the secondary grouping
+     * size can only be set with a pattern.
+     *
      * @param value
-     *            the number of digits grouped together
+     *            the number of digits grouped together.
      */
     public void setGroupingSize(int value) {
         dform.setGroupingSize(value);
@@ -530,8 +1051,7 @@
      * affects both parsing and formatting.
      * 
      * @param value
-     *            true if uses grouping,false otherwise.
-     * 
+     *            {@code true} if grouping is used; {@code false} otherwise.
      */
     @Override
     public void setGroupingUsed(boolean value) {
@@ -539,9 +1059,9 @@
     }
 
     /**
-     * This value indicates whether grouping will be used in this format.
+     * Indicates whether grouping will be used in this format.
      * 
-     * @return true if grouping is used,false otherwise.
+     * @return {@code true} if grouping is used; {@code false} otherwise.
      */
     @Override
     public boolean isGroupingUsed() {
@@ -550,12 +1070,14 @@
 
     /**
      * Sets the maximum number of fraction digits that are printed when
-     * formatting. If the maximum is less than the number of fraction digits,
-     * the least significant digits are truncated. Limit the maximum to
-     * DOUBLE_FRACTION_DIGITS.
+     * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+     * If the maximum is less than the number of fraction digits, the least
+     * significant digits are truncated. If the value passed is bigger than 340
+     * then it is replaced by 340. If the value passed is negative then it is
+     * replaced by 0.
      * 
      * @param value
-     *            the maximum number of fraction digits
+     *            the maximum number of fraction digits.
      */
     @Override
     public void setMaximumFractionDigits(int value) {
@@ -565,12 +1087,14 @@
 
     /**
      * Sets the maximum number of integer digits that are printed when
-     * formatting. If the maximum is less than the number of integer digits, the
-     * most significant digits are truncated. Limit the maximum to
-     * DOUBLE_INTEGER_DIGITS.
+     * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+     * If the maximum is less than the number of integer digits, the most
+     * significant digits are truncated. If the value passed is bigger than 309
+     * then it is replaced by 309. If the value passed is negative then it is
+     * replaced by 0.
      * 
      * @param value
-     *            the maximum number of integer digits
+     *            the maximum number of integer digits.
      */
     @Override
     public void setMaximumIntegerDigits(int value) {
@@ -580,10 +1104,12 @@
 
     /**
      * Sets the minimum number of fraction digits that are printed when
-     * formatting. Limit the minimum to DOUBLE_FRACTION_DIGITS.
+     * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+     * If the value passed is bigger than 340 then it is replaced by 340. If the
+     * value passed is negative then it is replaced by 0.
      * 
      * @param value
-     *            the minimum number of fraction digits
+     *            the minimum number of fraction digits.
      */
     @Override
     public void setMinimumFractionDigits(int value) {
@@ -593,10 +1119,12 @@
 
     /**
      * Sets the minimum number of integer digits that are printed when
-     * formatting. Limit the minimum to DOUBLE_INTEGER_DIGITS.
+     * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+     * If the value passed is bigger than 309 then it is replaced by 309. If the
+     * value passed is negative then it is replaced by 0.
      * 
      * @param value
-     *            the minimum number of integer digits
+     *            the minimum number of integer digits.
      */
     @Override
     public void setMinimumIntegerDigits(int value) {
@@ -609,7 +1137,7 @@
      * after parsing.
      * 
      * @param value
-     *            the multiplier
+     *            the multiplier.
      */
     public void setMultiplier(int value) {
         dform.setMultiplier(value);
@@ -619,7 +1147,7 @@
      * Sets the prefix which is formatted or parsed before a negative number.
      * 
      * @param value
-     *            the negative prefix
+     *            the negative prefix.
      */
     public void setNegativePrefix(String value) {
         dform.setNegativePrefix(value);
@@ -629,7 +1157,7 @@
      * Sets the suffix which is formatted or parsed after a negative number.
      * 
      * @param value
-     *            the negative suffix
+     *            the negative suffix.
      */
     public void setNegativeSuffix(String value) {
         dform.setNegativeSuffix(value);
@@ -639,7 +1167,7 @@
      * Sets the prefix which is formatted or parsed before a positive number.
      * 
      * @param value
-     *            the positive prefix
+     *            the positive prefix.
      */
     public void setPositivePrefix(String value) {
         dform.setPositivePrefix(value);
@@ -649,38 +1177,39 @@
      * Sets the suffix which is formatted or parsed after a positive number.
      * 
      * @param value
-     *            the positive suffix
+     *            the positive suffix.
      */
     public void setPositiveSuffix(String value) {
         dform.setPositiveSuffix(value);
     }
 
     /**
-     * Let users change the behavior of a DecimalFormat, If set to true all the
-     * returned objects will be of type BigDecimal
+     * Sets the behaviour of the parse method. If set to {@code true} then all
+     * the returned objects will be of type {@code BigDecimal}.
      * 
      * @param newValue
-     *            true if all the returned objects should be type of BigDecimal
+     *            {@code true} if all the returned objects should be of type
+     *            {@code BigDecimal}; {@code false} otherwise.
      */
     public void setParseBigDecimal(boolean newValue) {
         this.parseBigDecimal = newValue;
     }
 
     /**
-     * Answers the pattern of this DecimalFormat using localized pattern
+     * Returns the pattern of this decimal format using localized pattern
      * characters.
      * 
-     * @return the localized pattern
+     * @return the localized pattern.
      */
     public String toLocalizedPattern() {
         return dform.toLocalizedPattern();
     }
 
     /**
-     * Answers the pattern of this DecimalFormat using non-localized pattern
+     * Returns the pattern of this decimal format using non-localized pattern
      * characters.
      * 
-     * @return the non-localized pattern
+     * @return the non-localized pattern.
      */
     public String toPattern() {
         return dform.toPattern();

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java Thu May  7 08:42:00 2009
@@ -27,8 +27,15 @@
 import java.util.Locale;
 
 /**
- * DecimalFormatSymbols holds the symbols used in the formating and parsing of
- * numbers.
+ * Encapsulates the set of symbols (such as the decimal separator, the grouping
+ * separator, and so on) needed by {@code DecimalFormat} to format numbers.
+ * {@code DecimalFormat} internally creates an instance of
+ * {@code DecimalFormatSymbols} from its locale data. If you need to change any
+ * of these symbols, you can get the {@code DecimalFormatSymbols} object from
+ * your {@code DecimalFormat} and modify it.
+ *
+ * @see java.util.Locale
+ * @see DecimalFormat
  */
 public final class DecimalFormatSymbols implements Cloneable, Serializable {
 
@@ -48,8 +55,10 @@
     private String infinity, NaN, currencySymbol, intlCurrencySymbol;
 
     /**
-     * Constructs a new DecimalFormatSymbols containing the symbols for the
-     * default Locale.
+     * Constructs a new {@code DecimalFormatSymbols} containing the symbols for
+     * the default locale. Best practice is to create a {@code DecimalFormat}
+     * and then to get the {@code DecimalFormatSymbols} from that object by
+     * calling {@link DecimalFormat#getDecimalFormatSymbols()}.
      */
     public DecimalFormatSymbols() {
         this(Locale.getDefault());
@@ -57,10 +66,12 @@
 
     /**
      * Constructs a new DecimalFormatSymbols containing the symbols for the
-     * specified Locale.
+     * specified Locale. Best practice is to create a {@code DecimalFormat}
+     * and then to get the {@code DecimalFormatSymbols} from that object by
+     * calling {@link DecimalFormat#getDecimalFormatSymbols()}.
      * 
      * @param locale
-     *            the Locale
+     *            the locale.
      */
     public DecimalFormatSymbols(Locale locale) {
         com.ibm.icu.text.DecimalFormatSymbols icuSymbols = new com.ibm.icu.text.DecimalFormatSymbols(
@@ -90,10 +101,10 @@
     }
 
     /**
-     * Answers a new DecimalFormatSymbols with the same symbols as this
-     * DecimalFormatSymbols.
+     * Returns a new {@code DecimalFormatSymbols} with the same symbols as this
+     * {@code DecimalFormatSymbols}.
      * 
-     * @return a shallow copy of this DecimalFormatSymbols
+     * @return a shallow copy of this {@code DecimalFormatSymbols}.
      * 
      * @see java.lang.Cloneable
      */
@@ -109,15 +120,14 @@
     }
 
     /**
-     * Compares the specified object to this DecimalFormatSymbols and answer if
-     * they are equal. The object must be an instance of DecimalFormatSymbols
-     * with the same symbols.
+     * Compares the specified object to this {@code DecimalFormatSymbols} and
+     * indicates if they are equal. In order to be equal, {@code object} must be
+     * an instance of {@code DecimalFormatSymbols} and contain the same symbols.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this
-     *         DecimalFormatSymbols, false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code DecimalFormatSymbols}; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -136,16 +146,16 @@
     }
 
     /**
-     * Answers the currency.
+     * Returns the currency.
      * <p>
-     * <code>null<code> is returned
-     * if <code>setInternationalCurrencySymbol()</code> has been previously called
-     * with a value that is not a valid ISO 4217 currency code.
+     * {@code null} is returned if {@code setInternationalCurrencySymbol()} has
+     * been previously called with a value that is not a valid ISO 4217 currency
+     * code.
      * <p>
      *
-     * @return		the currency that was set in the constructor, <code>setCurrency()</code>,
-     * 				or <code>setInternationalCurrencySymbol()</code>, or </code>null</code>
-     * 
+     * @return the currency that was set in the constructor or by calling
+     *         {@code setCurrency()} or {@code setInternationalCurrencySymbol()},
+     *         or {@code null} if an invalid currency was set.
      * @see #setCurrency(Currency)
      * @see #setInternationalCurrencySymbol(String)
      */
@@ -154,55 +164,55 @@
     }
 
     /**
-     * Answers the international currency symbol.
+     * Returns the international currency symbol.
      * 
-     * @return a String
+     * @return the international currency symbol as string.
      */
     public String getInternationalCurrencySymbol() {
         return intlCurrencySymbol;
     }
 
     /**
-     * Answers the currency symbol.
+     * Returns the currency symbol.
      * 
-     * @return a String
+     * @return the currency symbol as string.
      */
     public String getCurrencySymbol() {
         return currencySymbol;
     }
 
     /**
-     * Answers the character which represents the decimal point in a number.
+     * Returns the character which represents the decimal point in a number.
      * 
-     * @return a char
+     * @return the decimal separator character.
      */
     public char getDecimalSeparator() {
         return patternChars[DecimalSeparator];
     }
 
     /**
-     * Answers the character which represents a single digit in a format
+     * Returns the character which represents a single digit in a format
      * pattern.
      * 
-     * @return a char
+     * @return the digit pattern character.
      */
     public char getDigit() {
         return patternChars[Digit];
     }
 
     /**
-     * Answers the character used as the thousands separator in a number.
+     * Returns the character used as the thousands separator in a number.
      * 
-     * @return a char
+     * @return the thousands separator character.
      */
     public char getGroupingSeparator() {
         return patternChars[GroupingSeparator];
     }
 
     /**
-     * Answers the String which represents infinity.
+     * Returns the string which represents infinity.
      * 
-     * @return a String
+     * @return the infinity symbol as a string.
      */
     public String getInfinity() {
         return infinity;
@@ -214,65 +224,65 @@
     }
 
     /**
-     * Answers the minus sign character.
+     * Returns the minus sign character.
      * 
-     * @return a char
+     * @return the minus sign as a character.
      */
     public char getMinusSign() {
         return patternChars[MinusSign];
     }
 
     /**
-     * Answers the character which represents the decimal point in a monetary
+     * Returns the character which represents the decimal point in a monetary
      * value.
      * 
-     * @return a char
+     * @return the monetary decimal point as a character.
      */
     public char getMonetaryDecimalSeparator() {
         return patternChars[MonetaryDecimalSeparator];
     }
 
     /**
-     * Answers the String which represents NaN.
+     * Returns the string which represents NaN.
      * 
-     * @return a String
+     * @return the symbol NaN as a string.
      */
     public String getNaN() {
         return NaN;
     }
 
     /**
-     * Answers the character which separates the positive and negative patterns
+     * Returns the character which separates the positive and negative patterns
      * in a format pattern.
      * 
-     * @return a char
+     * @return the pattern separator character.
      */
     public char getPatternSeparator() {
         return patternChars[PatternSeparator];
     }
 
     /**
-     * Answers the percent character.
+     * Returns the percent character.
      * 
-     * @return a char
+     * @return the percent character.
      */
     public char getPercent() {
         return patternChars[Percent];
     }
 
     /**
-     * Answers the mille percent sign character.
+     * Returns the per mill sign character.
      * 
-     * @return a char
+     * @return the per mill sign character.
      */
     public char getPerMill() {
         return patternChars[PerMill];
     }
 
     /**
-     * Answers the character which represents zero.
+     * Returns the character which represents zero.
      * 
-     * @return a char
+     * @return the zero character.
      */
     public char getZeroDigit() {
         return patternChars[ZeroDigit];
@@ -282,14 +292,6 @@
         return patternChars[Exponent];
     }
 
-    /**
-     * 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 new String(patternChars).hashCode() + infinity.hashCode()
@@ -300,15 +302,14 @@
     /**
      * Sets the currency.
      * <p>
-     * The international currency symbol and currency symbol are updated, but
-     * the min and max number of fraction digits stay the same.
+     * The international currency symbol and the currency symbol are updated,
+     * but the min and max number of fraction digits stays the same.
      * <p>
      * 
      * @param currency
-     *            the new currency
-     * 
-     * @throws java.lang.NullPointerException
-     *             if currency is null
+     *            the new currency.
+     * @throws NullPointerException
+     *             if {@code currency} is {@code null}.
      */
     public void setCurrency(Currency currency) {
         if (currency == null) {
@@ -325,13 +326,13 @@
     /**
      * Sets the international currency symbol.
      * <p>
-     * currency and currency symbol also are updated, if <code>value</code> is
-     * a valid ISO4217 currency code.
+     * The currency and currency symbol are also updated if {@code value} is a
+     * valid ISO4217 currency code.
      * <p>
      * The min and max number of fraction digits stay the same.
      * 
      * @param value
-     *            currency code
+     *            the currency code.
      */
     public void setInternationalCurrencySymbol(String value) {
         if (value == null) {
@@ -357,7 +358,7 @@
      * Sets the currency symbol.
      * 
      * @param value
-     *            a String
+     *            the currency symbol.
      */
     public void setCurrencySymbol(String value) {
         currencySymbol = value;
@@ -367,7 +368,7 @@
      * Sets the character which represents the decimal point in a number.
      * 
      * @param value
-     *            the decimal separator character
+     *            the decimal separator character.
      */
     public void setDecimalSeparator(char value) {
         patternChars[DecimalSeparator] = value;
@@ -377,7 +378,7 @@
      * Sets the character which represents a single digit in a format pattern.
      * 
      * @param value
-     *            the digit character
+     *            the digit character.
      */
     public void setDigit(char value) {
         patternChars[Digit] = value;
@@ -387,17 +388,17 @@
      * Sets the character used as the thousands separator in a number.
      * 
      * @param value
-     *            the grouping separator character
+     *            the grouping separator character.
      */
     public void setGroupingSeparator(char value) {
         patternChars[GroupingSeparator] = value;
     }
 
     /**
-     * Sets the String which represents infinity.
+     * Sets the string which represents infinity.
      * 
      * @param value
-     *            the String
+     *            the string representing infinity.
      */
     public void setInfinity(String value) {
         infinity = value;
@@ -407,7 +408,7 @@
      * Sets the minus sign character.
      * 
      * @param value
-     *            the minus sign character
+     *            the minus sign character.
      */
     public void setMinusSign(char value) {
         patternChars[MinusSign] = value;
@@ -418,17 +419,17 @@
      * value.
      * 
      * @param value
-     *            the monetary decimal separator character
+     *            the monetary decimal separator character.
      */
     public void setMonetaryDecimalSeparator(char value) {
         patternChars[MonetaryDecimalSeparator] = value;
     }
 
     /**
-     * Sets the String which represents NaN.
+     * Sets the string which represents NaN.
      * 
      * @param value
-     *            the String
+     *            the string representing NaN.
      */
     public void setNaN(String value) {
         NaN = value;
@@ -439,7 +440,7 @@
      * a format pattern.
      * 
      * @param value
-     *            the pattern separator character
+     *            the pattern separator character.
      */
     public void setPatternSeparator(char value) {
         patternChars[PatternSeparator] = value;
@@ -449,17 +450,17 @@
      * Sets the percent character.
      * 
      * @param value
-     *            the percent character
+     *            the percent character.
      */
     public void setPercent(char value) {
         patternChars[Percent] = value;
     }
 
     /**
-     * Sets the mille percent sign character.
+     * Sets the per mill sign character.
      * 
      * @param value
-     *            the mille percent character
+     *            the per mill character.
      */
     public void setPerMill(char value) {
         patternChars[PerMill] = value;
@@ -469,7 +470,7 @@
      * Sets the character which represents zero.
      * 
      * @param value
-     *            the zero digit character
+     *            the zero digit character.
      */
     public void setZeroDigit(char value) {
         patternChars[ZeroDigit] = value;

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java Thu May  7 08:42:00 2009
@@ -18,7 +18,16 @@
 package java.text;
 
 /**
- * FieldPosition is used to identify fields in formatted Strings.
+ * Identifies fields in formatted strings. If a {@code FieldPosition} is passed
+ * to the format method with such a parameter, then the indices will be set to
+ * the start and end indices of the field in the formatted string.
+ * <p>
+ * A {@code FieldPosition} can be created by using the integer constants in the
+ * various format classes (for example {@code NumberFormat.INTEGER_FIELD}) or
+ * one of the fields of type {@code Format.Field}.
+ * <p>
+ * If more than one field information is needed, the method
+ * {@link NumberFormat#formatToCharacterIterator(Object)} should be used.
  */
 public class FieldPosition {
 
@@ -27,20 +36,21 @@
     private Format.Field myAttribute;
 
     /**
-     * Constructs a new FieldPosition on the specified field.
+     * Constructs a new {@code FieldPosition} for the specified field.
      * 
      * @param field
-     *            the field to identify
+     *            the field to identify.
      */
     public FieldPosition(int field) {
         myField = field;
     }
 
     /**
-     * Constructs a new FieldPosition on the specified Field attribute.
+     * Constructs a new {@code FieldPosition} for the specified {@code Field}
+     * attribute.
      * 
      * @param attribute
-     *            the field attribute to identify
+     *            the field attribute to identify.
      */
     public FieldPosition(Format.Field attribute) {
         myAttribute = attribute;
@@ -48,13 +58,13 @@
     }
 
     /**
-     * Constructs a new FieldPosition on the specified Field attribute and field
-     * id.
+     * Constructs a new {@code FieldPosition} for the specified {@code Field}
+     * attribute and field id.
      * 
      * @param attribute
-     *            the field attribute to identify
+     *            the field attribute to identify.
      * @param field
-     *            the field to identify
+     *            the field to identify.
      */
     public FieldPosition(Format.Field attribute, int field) {
         myAttribute = attribute;
@@ -66,15 +76,14 @@
     }
 
     /**
-     * Compares the specified object to this FieldPosition and answer if they
-     * are equal. The object must be an instance of FieldPosition with the same
-     * field, begin index and end index.
+     * Compares the specified object to this field position and indicates if
+     * they are equal. In order to be equal, {@code object} must be an instance
+     * of {@code FieldPosition} with the same field, begin index and end index.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this fieldPosition,
-     *         false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this field
+     *         position; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -88,49 +97,41 @@
     }
 
     /**
-     * Answers the index of the beginning of the field.
+     * Returns the index of the beginning of the field.
      * 
-     * @return the first index of the field
+     * @return the first index of the field.
      */
     public int getBeginIndex() {
         return beginIndex;
     }
 
     /**
-     * Answers the index one past the end of the field.
+     * Returns the index one past the end of the field.
      * 
-     * @return one past the index of the last character in the field
+     * @return one past the index of the last character in the field.
      */
     public int getEndIndex() {
         return endIndex;
     }
 
     /**
-     * Answers the field which is being identified.
+     * Returns the field which is being identified.
      * 
-     * @return the field
+     * @return the field constant.
      */
     public int getField() {
         return myField;
     }
 
     /**
-     * Answers the attribute which is being identified.
+     * Returns the attribute which is being identified.
      * 
-     * @return the field
+     * @return the field.
      */
     public Format.Field getFieldAttribute() {
         return myAttribute;
     }
 
-    /**
-     * 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() {
         int attributeHash = (myAttribute == null) ? 0 : myAttribute.hashCode();
@@ -141,7 +142,7 @@
      * Sets the index of the beginning of the field.
      * 
      * @param index
-     *            the index of the first character in the field
+     *            the index of the first character in the field.
      */
     public void setBeginIndex(int index) {
         beginIndex = index;
@@ -151,16 +152,16 @@
      * Sets the index of the end of the field.
      * 
      * @param index
-     *            one past the index of the last character in the field
+     *            one past the index of the last character in the field.
      */
     public void setEndIndex(int index) {
         endIndex = index;
     }
 
     /**
-     * Answers the string representation of this FieldPosition.
+     * Returns the string representation of this field position.
      * 
-     * @return the string representation of this FieldPosition
+     * @return the string representation of this field position.
      */
     @Override
     public String toString() {



Mime
View raw message