harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772552 [4/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/Format.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Format.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Format.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/Format.java Thu May  7 08:42:00 2009
@@ -24,24 +24,54 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * Format is the abstract superclass of classes which format and parse objects
- * according to Locale specific rules.
+ * The base class for all formats.
+ * <p>
+ * This is an abstract base class which specifies the protocol for classes which
+ * convert other objects or values, such as numeric values and dates, and their
+ * string representations. In some cases these representations may be localized
+ * or contain localized characters or strings. For example, a numeric formatter
+ * such as {@code DecimalFormat} may convert a numeric value such as 12345 to
+ * the string "$12,345". It may also parse the string back into a numeric value.
+ * A date and time formatter like {@code SimpleDateFormat} may represent a
+ * specific date, encoded numerically, as a string such as "Wednesday, February
+ * 26, 1997 AD".
+ * <p>
+ * Many of the concrete subclasses of {@code Format} employ the notion of a
+ * pattern. A pattern is a string representation of the rules which govern the
+ * conversion between values and strings. For example, a {@code DecimalFormat}
+ * object may be associated with the pattern "$#,##0.00;($#,##0.00)", which is a
+ * common US English format for currency values, yielding strings such as
+ * "$1,234.45" for 1234.45, and "($987.65)" for -987.6543. The specific syntax
+ * of a pattern is defined by each subclass. Even though many subclasses use
+ * patterns, the notion of a pattern is not inherent to {@code Format} classes
+ * in general, and is not part of the explicit base class protocol.
+ * <p>
+ * Two complex formatting classes are worth mentioning: {@code MessageFormat}
+ * and {@code ChoiceFormat}. {@code ChoiceFormat} is a subclass of
+ * {@code NumberFormat} which allows the user to format different number ranges
+ * as strings. For instance, 0 may be represented as "no files", 1 as "one
+ * file", and any number greater than 1 as "many files". {@code MessageFormat}
+ * is a formatter which utilizes other {@code Format} objects to format a string
+ * containing multiple values. For instance, a {@code MessageFormat} object
+ * might produce the string "There are no files on the disk MyDisk on February
+ * 27, 1997." given the arguments 0, "MyDisk", and the date value of 2/27/97.
+ * See the {@link ChoiceFormat} and {@link MessageFormat} descriptions for
+ * further information.
  */
 public abstract class Format implements Serializable, Cloneable {
 
     private static final long serialVersionUID = -299282585814624189L;
 
     /**
-     * Constructs a new instance of Format.
-     * 
+     * Constructs a new {@code Format} instance.
      */
     public Format() {
     }
 
     /**
-     * Answers a copy of this Format.
+     * Returns a copy of this {@code Format} instance.
      * 
-     * @return a shallow copy of this Format
+     * @return a shallow copy of this format.
      * 
      * @see java.lang.Cloneable
      */
@@ -88,15 +118,13 @@
     }
 
     /**
-     * Formats the specified object using the rules of this Format.
-     * 
+     * Formats the specified object using the rules of this format.
      * 
      * @param object
-     *            the object to format
-     * @return the formatted String
-     * 
-     * @exception IllegalArgumentException
-     *                when the object cannot be formatted by this Format
+     *            the object to format.
+     * @return the formatted string.
+     * @throws IllegalArgumentException
+     *         if the object cannot be formatted by this format.
      */
     public final String format(Object object) {
         return format(object, new StringBuffer(), new FieldPosition(0))
@@ -104,54 +132,55 @@
     }
 
     /**
-     * Formats the specified object into the specified StringBuffer using the
-     * rules of this Format. If the field specified by the FieldPosition is
-     * formatted, set the begin and end index of the formatted field in the
-     * FieldPosition.
-     * 
+     * Appends the specified object to the specified string buffer using the
+     * rules of this format.
+     * <p>
+     * {@code field} is an input/output parameter. If its {@code field}
+     * member contains an enum value specifying a field on input, then its
+     * {@code beginIndex} and {@code endIndex} members will be updated with the
+     * text offset of the first occurrence of this field in the formatted text.
+     *
      * @param object
-     *            the object to format
+     *            the object to format.
      * @param buffer
-     *            the StringBuffer
+     *            the string buffer where the formatted string is appended to.
      * @param field
-     *            the FieldPosition
-     * @return the StringBuffer parameter <code>buffer</code>
-     * 
-     * @exception IllegalArgumentException
-     *                when the object cannot be formatted by this Format
+     *            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 object cannot be formatted by this format.
      */
     public abstract StringBuffer format(Object object, StringBuffer buffer,
             FieldPosition field);
 
     /**
      * Formats the specified object using the rules of this format and returns
-     * an AttributedCharacterIterator with the formatted String and no
+     * an {@code AttributedCharacterIterator} with the formatted string and no
      * attributes.
      * <p>
-     * Subclasses should return an AttributedCharacterIterator with the
+     * Subclasses should return an {@code AttributedCharacterIterator} with the
      * appropriate attributes.
-     * 
+     *
      * @param object
-     *            the object to format
-     * @return an AttributedCharacterIterator with the formatted object and
-     *         attributes
-     * 
-     * @exception IllegalArgumentException
-     *                when the object cannot be formatted by this Format
+     *            the object to format.
+     * @return an {@code AttributedCharacterIterator} with the formatted object
+     *         and attributes.
+     * @throws IllegalArgumentException
+     *            if the object cannot be formatted by this format.
      */
     public AttributedCharacterIterator formatToCharacterIterator(Object object) {
         return new AttributedString(format(object)).getIterator();
     }
 
     /**
-     * Parse the specified String using the rules of this Format.
+     * Parses the specified string using the rules of this format.
      * 
      * @param string
-     *            the String to parse
-     * @return the object resulting from the parse
-     * 
-     * @exception ParseException
-     *                when an error occurs during parsing
+     *            the string to parse.
+     * @return the object resulting from the parse.
+     * @throws ParseException
+     *            if an error occurs during parsing.
      */
     public Object parseObject(String string) throws ParseException {
         ParsePosition position = new ParsePosition(0);
@@ -163,17 +192,22 @@
     }
 
     /**
-     * Parse 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 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 the object 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 object resulting from the parse or {@code null} if there is
+     *         an error.
      */
     public abstract Object parseObject(String string, ParsePosition position);
 
@@ -255,16 +289,20 @@
     }
 
     /**
-     * This inner class is used to represent Format attributes in the
-     * AttributedCharacterIterator that formatToCharacterIterator() method
-     * returns in the Format subclasses.
+     * Inner class used to represent {@code Format} attributes in the
+     * {@code AttributedCharacterIterator} that the
+     * {@code formatToCharacterIterator()} method returns in {@code Format}
+     * subclasses.
      */
     public static class Field extends AttributedCharacterIterator.Attribute {
 
         private static final long serialVersionUID = 276966692217360283L;
 
         /**
-         * Constructs a new instance of Field with the given fieldName.
+         * Constructs a new instance of {@code Field} with the given field name.
+         *
+         * @param fieldName
+         *            the field name.
          */
         protected Field(String fieldName) {
             super(fieldName);

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/MessageFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/MessageFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/MessageFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/MessageFormat.java Thu May  7 08:42:00 2009
@@ -31,9 +31,308 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * MessageFormat is used to format and parse arguments based on a pattern. The
- * pattern specifies how each argument will be formatted and concatenated with
- * other text to produce the formatted output.
+ * Produces concatenated
+ * messages in language-neutral way. Use this class to construct messages
+ * displayed for end users.
+ * <p>
+ * {@code MessageFormat} takes a set of objects, formats them and then
+ * inserts the formatted strings into the pattern at the appropriate places.
+ * <p>
+ * <strong>Note:</strong> {@code MessageFormat} differs from the other
+ * {@code Format} classes in that you create a {@code MessageFormat}
+ * object with one of its constructors (not with a {@code getInstance}
+ * style factory method). The factory methods aren't necessary because
+ * {@code MessageFormat} itself doesn't implement locale specific
+ * behavior. Any locale specific behavior is defined by the pattern that you
+ * provide as well as the subformats used for inserted arguments.
+ *
+ * <h4><a name="patterns">Patterns and their interpretation</a></h4>
+ *
+ * {@code MessageFormat} uses patterns of the following form:
+ * <blockquote>
+ *
+ * <pre>
+ * <i>MessageFormatPattern:</i>
+ *         <i>String</i>
+ *         <i>MessageFormatPattern</i> <i>FormatElement</i> <i>String</i>
+ * <i>FormatElement:</i>
+ *         { <i>ArgumentIndex</i> }
+ *         { <i>ArgumentIndex</i> , <i>FormatType</i> }
+ *         { <i>ArgumentIndex</i> , <i>FormatType</i> , <i>FormatStyle</i> }
+ * <i>FormatType: one of </i>
+ *         number date time choice
+ * <i>FormatStyle:</i>
+ *         short
+ *         medium
+ *         long
+ *         full
+ *         integer
+ *         currency
+ *         percent
+ *         <i>SubformatPattern</i>
+ * <i>String:</i>
+ *         <i>StringPart&lt;sub&gt;opt&lt;/sub&gt;</i>
+ *         <i>String</i> <i>StringPart</i>
+ * <i>StringPart:</i>
+ *         ''
+ *         ' <i>QuotedString</i> '
+ *         <i>UnquotedString</i>
+ * <i>SubformatPattern:</i>
+ *         <i>SubformatPatternPart&lt;sub&gt;opt&lt;/sub&gt;</i>
+ *         <i>SubformatPattern</i> <i>SubformatPatternPart</i>
+ * <i>SubFormatPatternPart:</i>
+ *         ' <i>QuotedPattern</i> '
+ *         <i>UnquotedPattern</i>
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * <p>
+ * Within a <i>String</i>, {@code "''"} represents a single quote. A
+ * <i>QuotedString</i> can contain arbitrary characters except single quotes;
+ * the surrounding single quotes are removed. An <i>UnquotedString</i> can
+ * contain arbitrary characters except single quotes and left curly brackets.
+ * Thus, a string that should result in the formatted message "'{0}'" can be
+ * written as {@code "'''{'0}''"} or {@code "'''{0}'''"}.
+ * <p>
+ * Within a <i>SubformatPattern</i>, different rules apply. A <i>QuotedPattern</i>
+ * can contain arbitrary characters except single quotes, but the surrounding
+ * single quotes are <strong>not</strong> removed, so they may be interpreted
+ * by the subformat. For example, {@code "{1,number,$'#',##}"} will
+ * produce a number format with the hash-sign quoted, with a result such as:
+ * "$#31,45". An <i>UnquotedPattern</i> can contain arbitrary characters except
+ * single quotes, but curly braces within it must be balanced. For example,
+ * {@code "ab {0} de"} and {@code "ab '}' de"} are valid subformat
+ * patterns, but {@code "ab {0'}' de"} and {@code "ab } de"} are
+ * not.
+ * <dl>
+ * <dt><b>Warning:</b></dt>
+ * <dd>The rules for using quotes within message format patterns unfortunately
+ * have shown to be somewhat confusing. In particular, it isn't always obvious
+ * to localizers whether single quotes need to be doubled or not. Make sure to
+ * inform localizers about the rules, and tell them (for example, by using
+ * comments in resource bundle source files) which strings will be processed by
+ * {@code MessageFormat}. Note that localizers may need to use single quotes in
+ * translated strings where the original version doesn't have them. <br>
+ * Note also that the simplest way to avoid the problem is to use the real
+ * apostrophe (single quote) character \u2019 (') for human-readable text, and
+ * to use the ASCII apostrophe (\u0027 ' ) only in program syntax, like quoting
+ * in {@code MessageFormat}. See the annotations for U+0027 Apostrophe in The Unicode
+ * Standard.
+ * </dl>
+ * <p>
+ * The <i>ArgumentIndex</i> value is a non-negative integer written using the
+ * digits '0' through '9', and represents an index into the
+ * {@code arguments} array passed to the {@code format} methods or
+ * the result array returned by the {@code parse} methods.
+ * <p>
+ * The <i>FormatType</i> and <i>FormatStyle</i> values are used to create a
+ * {@code Format} instance for the format element. The following table
+ * shows how the values map to {@code Format} instances. Combinations not shown in the
+ * table are illegal. A <i>SubformatPattern</i> must be a valid pattern string
+ * for the {@code Format} subclass used.
+ * <p>
+ * <table border=1>
+ * <tr>
+ * <th>Format Type</th>
+ * <th>Format Style</th>
+ * <th>Subformat Created</th>
+ * </tr>
+ * <tr>
+ * <td colspan="2"><i>(none)</i></td>
+ * <td>{@code null}</td>
+ * </tr>
+ * <tr>
+ * <td rowspan="5">{@code number}</td>
+ * <td><i>(none)</i></td>
+ * <td>{@code NumberFormat.getInstance(getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code integer}</td>
+ * <td>{@code NumberFormat.getIntegerInstance(getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code currency}</td>
+ * <td>{@code NumberFormat.getCurrencyInstance(getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code percent}</td>
+ * <td>{@code NumberFormat.getPercentInstance(getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td><i>SubformatPattern</i></td>
+ * <td>{@code new DecimalFormat(subformatPattern, new DecimalFormatSymbols(getLocale()))}</td>
+ * </tr>
+ * <tr>
+ * <td rowspan="6">{@code date}</td>
+ * <td><i>(none)</i></td>
+ * <td>{@code DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code short}</td>
+ * <td>{@code DateFormat.getDateInstance(DateFormat.SHORT, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code medium}</td>
+ * <td>{@code DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code long}</td>
+ * <td>{@code DateFormat.getDateInstance(DateFormat.LONG, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code full}</td>
+ * <td>{@code DateFormat.getDateInstance(DateFormat.FULL, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td><i>SubformatPattern</i></td>
+ * <td>{@code new SimpleDateFormat(subformatPattern, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td rowspan="6">{@code time}</td>
+ * <td><i>(none)</i></td>
+ * <td>{@code DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code short}</td>
+ * <td>{@code DateFormat.getTimeInstance(DateFormat.SHORT, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code medium}</td>
+ * <td>{@code DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code long}</td>
+ * <td>{@code DateFormat.getTimeInstance(DateFormat.LONG, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code full}</td>
+ * <td>{@code DateFormat.getTimeInstance(DateFormat.FULL, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td><i>SubformatPattern</i></td>
+ * <td>{@code new SimpleDateFormat(subformatPattern, getLocale())}</td>
+ * </tr>
+ * <tr>
+ * <td>{@code choice}</td>
+ * <td><i>SubformatPattern</i></td>
+ * <td>{@code new ChoiceFormat(subformatPattern)}</td>
+ * </tr>
+ * </table>
+ *
+ * <h4>Usage Information</h4>
+ * <p>
+ * Here are some examples of usage: <blockquote>
+ *
+ * <pre>
+ * Object[] arguments = {
+ *         new Integer(7), new Date(System.currentTimeMillis()),
+ *         "a disturbance in the Force"};
+ * String result = MessageFormat.format(
+ *         "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
+ *         arguments);
+ * <em>
+ * Output:
+ * </em>
+ * At 12:30 PM on Jul 3, 2053, there was a disturbance in the Force on planet 7.
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Typically, the message format will come from resources, and the
+ * arguments will be dynamically set at runtime.
+ * <p>
+ * Example 2: <blockquote>
+ *
+ * <pre>
+ * Object[] testArgs = {new Long(3), "MyDisk"};
+ * MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0} file(s).");
+ * System.out.println(form.format(testArgs));
+ * <em>
+ * Output with different testArgs:
+ * </em>
+ * The disk "MyDisk" contains 0 file(s).
+ * The disk "MyDisk" contains 1 file(s).
+ * The disk "MyDisk" contains 1,273 file(s).
+ * </pre>
+ *
+ * </blockquote>
+ *
+ * <p>
+ * For more sophisticated patterns, you can use a {@code ChoiceFormat} to
+ * get output such as:
+ * <blockquote>
+ *
+ * <pre>
+ * MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}.");
+ * double[] filelimits = {0,1,2};
+ * String[] filepart = {"no files","one file","{0,number} files"};
+ * ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart);
+ * form.setFormatByArgumentIndex(0, fileform);
+ * Object[] testArgs = {new Long(12373), "MyDisk"};
+ * System.out.println(form.format(testArgs));
+ * <em>
+ * Output (with different testArgs):
+ * </em>
+ * The disk "MyDisk" contains no files.
+ * The disk "MyDisk" contains one file.
+ * The disk "MyDisk" contains 1,273 files.
+ * </pre>
+ *
+ * </blockquote> You can either do this programmatically, as in the above
+ * example, or by using a pattern (see {@link ChoiceFormat} for more
+ * information) as in: <blockquote>
+ *
+ * <pre>
+ * form.applyPattern("There {0,choice,0#are no files|1#is one file|1&lt;are {0,number,integer} files}.");
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * <strong>Note:</strong> As we see above, the string produced by a
+ * {@code ChoiceFormat} in {@code MessageFormat} is treated
+ * specially; occurances of '{' are used to indicated subformats, and cause
+ * recursion. If you create both a {@code MessageFormat} and
+ * {@code ChoiceFormat} programmatically (instead of using the string
+ * patterns), then be careful not to produce a format that recurses on itself,
+ * which will cause an infinite loop.
+ * <p>
+ * When a single argument is parsed more than once in the string, the last match
+ * will be the final result of the parsing. For example:
+ * <blockquote>
+ * <pre>
+ * MessageFormat mf = new MessageFormat("{0,number,#.##}, {0,number,#.#}");
+ * Object[] objs = {new Double(3.1415)};
+ * String result = mf.format(objs);
+ * // result now equals "3.14, 3.1"
+ * objs = null;
+ * objs = mf.parse(result, new ParsePosition(0));
+ * // objs now equals {new Double(3.1)}
+ * </pre>
+ * </blockquote>
+ * <p>
+ * Likewise, parsing with a {@code MessageFormat} object using patterns
+ * containing multiple occurrences of the same argument would return the last
+ * match. For example:
+ * <blockquote>
+ * <pre>
+ * MessageFormat mf = new MessageFormat("{0}, {0}, {0}");
+ * String forParsing = "x, y, z";
+ * Object[] objs = mf.parse(forParsing, new ParsePosition(0));
+ * // result now equals {new String("z")}
+ * </pre>
+ * </blockquote>
+ * <h4><a name="synchronization">Synchronization</a></h4>
+ * <p>
+ * Message 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 java.util.Locale
+ * @see Format
+ * @see NumberFormat
+ * @see DecimalFormat
+ * @see ChoiceFormat
  */
 public class MessageFormat extends Format {
 
@@ -52,16 +351,15 @@
     transient private int maxArgumentIndex;
 
     /**
-     * Constructs a new MessageFormat using the specified pattern and the
-     * specified Locale for Formats.
+     * Constructs a new {@code MessageFormat} using the specified pattern and
+     * the specified locale for formats.
      * 
      * @param template
-     *            the pattern
+     *            the pattern.
      * @param locale
-     *            the locale
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the locale.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public MessageFormat(String template, Locale locale) {
         this.locale = locale;
@@ -69,27 +367,25 @@
     }
 
     /**
-     * Constructs a new MessageFormat using the specified pattern and the
-     * default Locale for Formats.
+     * Constructs a new {@code MessageFormat} using the specified pattern and
+     * the default locale for formats.
      * 
      * @param template
-     *            the pattern
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the pattern.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public MessageFormat(String template) {
         applyPattern(template);
     }
 
     /**
-     * Changes this MessageFormat to use the specified pattern.
+     * Changes this {@code MessageFormat} to use the specified pattern.
      * 
      * @param template
-     *            the pattern
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the new pattern.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public void applyPattern(String template) {
         int length = template.length();
@@ -156,11 +452,10 @@
     }
 
     /**
-     * Answers a new instance of MessageFormat with the same pattern and Formats
-     * as this MessageFormat.
-     * 
-     * @return a shallow copy of this MessageFormat
+     * Returns a new instance of {@code MessageFormat} with the same pattern and
+     * formats as this {@code MessageFormat}.
      * 
+     * @return a shallow copy of this {@code MessageFormat}.
      * @see java.lang.Cloneable
      */
     @Override
@@ -177,15 +472,14 @@
     }
 
     /**
-     * Compares the specified object to this MessageFormat and answer if they
-     * are equal. The object must be an instance of MessageFormat and have the
-     * same pattern.
+     * Compares the specified object to this {@code MessageFormat} and indicates
+     * if they are equal. In order to be equal, {@code object} must be an
+     * instance of {@code MessageFormat} and have the same pattern.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this MessageFormat,
-     *         false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code MessageFormat}; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -213,19 +507,18 @@
     }
 
     /**
-     * Formats the specified object using the rules of this MessageFormat and
-     * returns an AttributedCharacterIterator with the formatted message and
-     * attributes. The AttributedCharacterIterator returned also includes the
-     * attributes from the formats of this MessageFormat.
+     * Formats the specified object using the rules of this message format and
+     * returns an {@code AttributedCharacterIterator} with the formatted message and
+     * attributes. The {@code AttributedCharacterIterator} returned also includes the
+     * attributes from the formats of this message format.
      * 
      * @param object
-     *            the object to format
-     * @return an AttributedCharacterIterator with the formatted message and
-     *         attributes
-     * 
-     * @exception IllegalArgumentException
-     *                when the arguments in the object array cannot be formatted
-     *                by this Format
+     *            the object to format.
+     * @return an {@code AttributedCharacterIterator} with the formatted message and
+     *         attributes.
+     * @throws IllegalArgumentException
+     *            if the arguments in the object array cannot be formatted
+     *            by this message format.
      */
     @Override
     public AttributedCharacterIterator formatToCharacterIterator(Object object) {
@@ -253,23 +546,22 @@
     }
 
     /**
-     * Formats the Object arguments into the specified StringBuffer using the
-     * pattern of this MessageFormat.
+     * Converts the specified objects into a string which it appends to the
+     * specified string buffer using the pattern of this message format.
      * <p>
-     * If Field Attribute of the FieldPosition supplied is
-     * MessageFormat.Field.ARGUMENT, then begin and end index of this field
-     * position is set to the location of the first occurrence of a message
-     * format argument. Otherwise the FieldPosition is ignored
-     * <p>
-     * 
+     * If the {@code field} member of the specified {@code FieldPosition} is
+     * {@code MessageFormat.Field.ARGUMENT}, then the begin and end index of
+     * this field position is set to the location of the first occurrence of a
+     * message format argument. Otherwise, the {@code FieldPosition} is ignored.
+     *
      * @param objects
-     *            the array of Objects to format
+     *            the array of objects to format.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted message to.
      * @param field
-     *            a 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 final StringBuffer format(Object[] objects, StringBuffer buffer,
             FieldPosition field) {
@@ -411,19 +703,33 @@
     }
 
     /**
-     * Formats the specified object into the specified StringBuffer using the
-     * pattern of this MessageFormat.
+     * Converts the specified objects into a string which it appends to the
+     * specified string buffer using the pattern of this message format.
+     * <p>
+     * If the {@code field} member of the specified {@code FieldPosition} is
+     * {@code MessageFormat.Field.ARGUMENT}, then the begin and end index of
+     * this field position is set to the location of the first occurrence of a
+     * message format argument. Otherwise, the {@code FieldPosition} is ignored.
+     * <p>
+     * Calling this method is equivalent to calling
+     * <blockquote>
      * 
+     * <pre>
+     * format((Object[])object, buffer, field)
+     * </pre>
+     *
+     * </blockquote>
+     *
      * @param object
-     *            the object to format, must be an array of Object
+     *            the object to format, must be an array of {@code Object}.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted message to.
      * @param field
-     *            a FieldPosition which is ignored
-     * @return the StringBuffer parameter <code>buffer</code>
-     * 
-     * @exception ClassCastException
-     *                when <code>object</code> is not an array of Object
+     *            on input: an optional alignment field; on output: the offsets
+     *            of the alignment field in the formatted text.
+     * @return the string buffer.
+     * @throws ClassCastException
+     *             if {@code object} is not an array of {@code Object}.
      */
     @Override
     public final StringBuffer format(Object object, StringBuffer buffer,
@@ -432,16 +738,15 @@
     }
 
     /**
-     * Formats the Object arguments using the specified MessageFormat pattern.
+     * Formats the supplied objects using the specified message format pattern.
      * 
      * @param template
-     *            the pattern
+     *            the pattern to use for formatting.
      * @param objects
-     *            the array of Objects to format
-     * @return the formatted result
-     * 
-     * @exception IllegalArgumentException
-     *                when the pattern cannot be parsed
+     *            the array of objects to format.
+     * @return the formatted result.
+     * @throws IllegalArgumentException
+     *            if the pattern cannot be parsed.
      */
     public static String format(String template, Object... objects) {
         if (objects != null) {
@@ -455,20 +760,20 @@
     }
 
     /**
-     * Answers the Formats of this MessageFormat.
+     * Returns the {@code Format} instances used by this message format.
      * 
-     * @return an array of Format
+     * @return an array of {@code Format} instances.
      */
     public Format[] getFormats() {
         return formats.clone();
     }
 
     /**
-     * Answers the formats used for each argument index. If an argument is
-     * placed more than once in the pattern string, than returns the format of
-     * the last one.
+     * Returns the formats used for each argument index. If an argument is
+     * placed more than once in the pattern string, then this returns the format
+     * of the last one.
      * 
-     * @return an array of formats, ordered by argument index
+     * @return an array of formats, ordered by argument index.
      */
     public Format[] getFormatsByArgumentIndex() {
         Format[] answer = new Format[maxArgumentIndex + 1];
@@ -479,11 +784,13 @@
     }
 
     /**
-     * Sets the format used for argument at index <code>argIndex</code>to
-     * <code>format</code>
+     * Sets the format used for the argument at index {@code argIndex} to
+     * {@code format}.
      * 
      * @param argIndex
+     *            the index of the format to set.
      * @param format
+     *            the format that will be set at index {@code argIndex}.
      */
     public void setFormatByArgumentIndex(int argIndex, Format format) {
         for (int i = 0; i < maxOffset + 1; i++) {
@@ -494,10 +801,11 @@
     }
 
     /**
-     * Sets the formats used for each argument <code>The formats</code> array
+     * Sets the formats used for each argument. The {@code formats} array
      * elements should be in the order of the argument indices.
      * 
      * @param formats
+     *            the formats in an array.
      */
     public void setFormatsByArgumentIndex(Format[] formats) {
         for (int j = 0; j < formats.length; j++) {
@@ -510,22 +818,14 @@
     }
 
     /**
-     * Answers the Locale used when creating Formats.
+     * Returns the locale used when creating formats.
      * 
-     * @return the Locale used to create Formats
+     * @return the locale used to create formats.
      */
     public Locale getLocale() {
         return locale;
     }
 
-    /**
-     * 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 = 0;
@@ -545,15 +845,14 @@
     }
 
     /**
-     * Parse the message arguments from the specified String using the rules of
-     * this MessageFormat.
+     * Parses the message arguments from the specified string using the rules of
+     * this message format.
      * 
      * @param string
-     *            the String to parse
-     * @return the array of Object arguments resulting from the parse
-     * 
-     * @exception ParseException
-     *                when an error occurs during parsing
+     *            the string to parse.
+     * @return the array of {@code Object} arguments resulting from the parse.
+     * @throws ParseException
+     *            if an error occurs during parsing.
      */
     public Object[] parse(String string) throws ParseException {
         ParsePosition position = new ParsePosition(0);
@@ -565,19 +864,23 @@
     }
 
     /**
-     * Parse the message argument 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 the message argument 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 the array of Object arguments 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 array of objects resulting from the parse, or {@code null} if
+     *         there is an error.
      */
     public Object[] parse(String string, ParsePosition position) {
         if (string == null) {
@@ -632,19 +935,23 @@
     }
 
     /**
-     * Parse the message argument 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 the message argument 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 the array of Object arguments 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 array of objects resulting from the parse, or {@code null} if
+     *         there is an error.
      */
     @Override
     public Object parseObject(String string, ParsePosition position) {
@@ -760,22 +1067,22 @@
     }
 
     /**
-     * Sets the specified Format used by this MessageFormat.
+     * Sets the specified format used by this message format.
      * 
      * @param offset
-     *            the format to change
+     *            the index of the format to change.
      * @param format
-     *            the Format
+     *            the {@code Format} that replaces the old format.
      */
     public void setFormat(int offset, Format format) {
         formats[offset] = format;
     }
 
     /**
-     * Sets the Formats used by this MessageFormat.
+     * Sets the formats used by this message format.
      * 
      * @param formats
-     *            an array of Format
+     *            an array of {@code Format}.
      */
     public void setFormats(Format[] formats) {
         int min = this.formats.length;
@@ -788,10 +1095,12 @@
     }
 
     /**
-     * Sets the Locale to use when creating Formats.
+     * Sets the locale to use when creating {@code Format} instances. Changing
+     * the locale may change the behavior of {@code applyPattern},
+     * {@code toPattern}, {@code format} and {@code formatToCharacterIterator}.
      * 
      * @param locale
-     *            the Locale
+     *            the new locale.
      */
     public void setLocale(Locale locale) {
         this.locale = locale;
@@ -858,9 +1167,9 @@
     }
 
     /**
-     * Answers the pattern of this MessageFormat.
+     * Returns the pattern of this message format.
      * 
-     * @return the pattern
+     * @return the pattern.
      */
     public String toPattern() {
         StringBuffer buffer = new StringBuffer();
@@ -990,29 +1299,39 @@
 
     /**
      * The instances of this inner class are used as attribute keys in
-     * AttributedCharacterIterator that
-     * MessageFormat.formatToCharacterIterator() method returns.
+     * {@code AttributedCharacterIterator} that the
+     * {@link MessageFormat#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.
      */
     public static class Field extends Format.Field {
 
         private static final long serialVersionUID = 7899943957617360810L;
 
+        /**
+         * This constant stands for the message argument.
+         */
         public static final Field ARGUMENT = new Field("message argument field"); //$NON-NLS-1$
 
         /**
-         * Constructs a new instance of MessageFormat.Field with the given field
-         * name.
+         * Constructs a new instance of {@code MessageFormat.Field} with the
+         * given field name.
+         *
+         * @param fieldName
+         *            the field name.
          */
         protected Field(String fieldName) {
             super(fieldName);
         }
 
         /**
-         * serialization method resolve instances to the constant
-         * MessageFormat.Field values
+         * Resolves instances that are deserialized to the constant
+         * {@code MessageFormat.Field} values.
+         *
+         * @return the resolved field object.
+         * @throws InvalidObjectException
+         *             if an error occurs while resolving the field object.
          */
         @Override
         protected Object readResolve() throws InvalidObjectException {

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/NumberFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/NumberFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/NumberFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/NumberFormat.java Thu May  7 08:42:00 2009
@@ -28,20 +28,127 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * NumberFormat is the abstract superclass of Formats which format and parse
- * Numbers.
+ * The abstract base class for all number formats. This class provides the
+ * interface for formatting and parsing numbers. {@code NumberFormat} also
+ * provides methods for determining which locales have number formats, and what
+ * their names are.
+ * <p>
+ * {@code NumberFormat} helps you to format and parse numbers for any locale.
+ * Your code can be completely independent of the locale conventions for decimal
+ * points, thousands-separators, or even the particular decimal digits used, or
+ * whether the number format is even decimal.
+ * <p>
+ * To format a number for the current locale, use one of the factory class
+ * methods:
+ * <blockquote>
+ *
+ * <pre>
+ * myString = NumberFormat.getInstance().format(myNumber);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * If you are formatting multiple numbers, 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>
+ * NumberFormat nf = NumberFormat.getInstance();
+ * for (int i = 0; i &lt; a.length; ++i) {
+ *     output.println(nf.format(myNumber[i]) + &quot;; &quot;);
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * To format a number for a different locale, specify it in the call to
+ * {@code getInstance}.
+ * <blockquote>
+ *
+ * <pre>
+ * NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * You can also use a {@code NumberFormat} to parse numbers:
+ * <blockquote>
+ *
+ * <pre>
+ * myNumber = nf.parse(myString);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Use {@code getInstance} or {@code getNumberInstance} to get the normal number
+ * format. Use {@code getIntegerInstance} to get an integer number format. Use
+ * {@code getCurrencyInstance} to get the currency number format and use
+ * {@code getPercentInstance} to get a format for displaying percentages. With
+ * this format, a fraction like 0.53 is displayed as 53%.
+ * <p>
+ * You can also control the display of numbers with methods such as
+ * {@code setMinimumFractionDigits}. If you want even more control over the
+ * format or parsing, or want to give your users more control, you can try
+ * casting the {@code NumberFormat} you get from the factory methods to a
+ * {@code DecimalFormat}. This will work for the vast majority of locales; just
+ * remember to put it in a {@code try} block in case you encounter an unusual
+ * one.
+ * <p>
+ * {@code NumberFormat} is designed such that some controls work for formatting
+ * and others work for parsing. For example, {@code setParseIntegerOnly} only
+ * affects parsing: If set to {@code true}, "3456.78" is parsed as 3456 (and
+ * leaves the parse position just after '6'); if set to {@code false},
+ * "3456.78" is parsed as 3456.78 (and leaves the parse position just after
+ * '8'). This is independent of formatting.
+ * <p>
+ * You can also use forms of the {@code parse} and {@code format} methods with
+ * {@code ParsePosition} and {@code FieldPosition} to allow you to:
+ * <ul>
+ * <li>progressively parse through pieces of a string;</li>
+ * <li>align the decimal point and other areas.</li>
+ * </ul>
+ * For example, you can align numbers in two ways:
+ * <ol>
+ * <li> If you are using a monospaced font with spacing for alignment, you can
+ * pass the {@code FieldPosition} in your format call, with {@code field} =
+ * {@code INTEGER_FIELD}. On output, {@code getEndIndex} will be set to the
+ * offset between the last character of the integer and the decimal. Add
+ * (desiredSpaceCount - getEndIndex) spaces to the front of the string.</li>
+ * <li> If you are using proportional fonts, instead of padding with spaces,
+ * measure the width of the string in pixels from the start to
+ * {@code getEndIndex}. Then move the pen by (desiredPixelWidth -
+ * widthToAlignmentPoint) before drawing the text. This also works where there
+ * is no decimal but possibly additional characters before or after the number,
+ * for example with parentheses in negative numbers: "(12)" for -12.</li>
+ * </ol>
+ * <h4>Synchronization</h4>
+ * <p>
+ * Number formats are generally 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.
+ * <p>
+ * <h4>DecimalFormat</h4>
+ * <p>
+ * {@code DecimalFormat} is the concrete implementation of {@code NumberFormat},
+ * and the {@code NumberFormat} API is essentially an abstraction of
+ * {@code DecimalFormat's} API. Refer to {@code DecimalFormat} for more
+ * information about this API.
+ *
+ * @see DecimalFormat
+ * @see java.text.ChoiceFormat
  */
 public abstract class NumberFormat extends Format {
 
     private static final long serialVersionUID = -2308460125733713944L;
 
     /**
-     * Field constant.
+     * Field constant identifying the integer part of a number.
      */
     public static final int INTEGER_FIELD = 0;
 
     /**
-     * Field constant.
+     * Field constant identifying the fractional part of a number.
      */
     public static final int FRACTION_FIELD = 1;
 
@@ -51,16 +158,16 @@
             maximumFractionDigits = 3, minimumFractionDigits = 0;
 
     /**
-     * Constructs a new instance of DateFormat.
+     * Constructs a new instance of {@code NumberFormat}.
      */
     public NumberFormat() {
     }
 
     /**
-     * Answers a new NumberFormat with the same properties as this NumberFormat.
-     * 
-     * @return a shallow copy of this NumberFormat
+     * Returns a new {@code NumberFormat} with the same properties as this
+     * {@code NumberFormat}.
      * 
+     * @return a shallow copy of this {@code NumberFormat}.
      * @see java.lang.Cloneable
      */
     @Override
@@ -69,15 +176,14 @@
     }
 
     /**
-     * Compares the specified object to this NumberFormat and answer if they are
-     * equal. The object must be an instance of NumberFormat and have the same
-     * properties.
+     * Compares the specified object to this number format and indicates if
+     * they are equal. In order to be equal, {@code object} must be an instance
+     * of {@code NumberFormat} 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 NumberFormat, false
-     *         otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this number
+     *         format; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -98,11 +204,11 @@
     }
 
     /**
-     * Formats the specified double using the rules of this NumberFormat.
+     * Formats the specified double using the rules of this number format.
      * 
      * @param value
-     *            the double to format
-     * @return the formatted String
+     *            the double to format.
+     * @return the formatted string.
      */
     public final String format(double value) {
         return format(value, new StringBuffer(), new FieldPosition(0))
@@ -110,28 +216,33 @@
     }
 
     /**
-     * Formats the double value into the specified StringBuffer using the rules
-     * of this NumberFormat. 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
+     * number 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 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(double value, StringBuffer buffer,
             FieldPosition field);
 
     /**
-     * Formats the specified long using the rules of this NumberFormat.
+     * Formats the specified long using the rules of this number format.
      * 
      * @param value
-     *            the long to format
-     * @return the formatted String
+     *            the long to format.
+     * @return the formatted string.
      */
     public final String format(long value) {
         return format(value, new StringBuffer(), new FieldPosition(0))
@@ -139,38 +250,46 @@
     }
 
     /**
-     * Formats the long value into the specified StringBuffer using the rules of
-     * this NumberFormat. 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
+     * number 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 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(long value, StringBuffer buffer,
             FieldPosition field);
 
     /**
-     * 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 number
+     * 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 Number
+     *            the object to format, must be a {@code Number}.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted number to.
      * @param field
-     *            the FieldPosition
-     * @return the StringBuffer parameter <code>buffer</code>
-     * 
-     * @exception IllegalArgumentException
-     *                when the object is not 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 not an instance of {@code Number}.
      */
     @Override
     public StringBuffer format(Object object, StringBuffer buffer,
@@ -187,46 +306,47 @@
     }
 
     /**
-     * Gets the list of installed Locales which support NumberFormat.
+     * Gets the list of installed locales which support {@code NumberFormat}.
      * 
-     * @return an array of Locale
+     * @return an array of locales.
      */
     public static Locale[] getAvailableLocales() {
         return Locale.getAvailableLocales();
     }
 
     /**
-     * Answers the currency used by this number format
+     * Returns the currency used by this number format.
      * <p>
-     * This implementation throws UnsupportedOperationException, concrete sub
-     * classes should override if they support currency formatting.
+     * This implementation throws {@code UnsupportedOperationException},
+     * concrete subclasses should override this method if they support currency
+     * formatting.
      * <p>
      * 
-     * @return currency currency that was set in getInstance() or in
-     *         setCurrency(), or null
-     * @throws java.lang.UnsupportedOperationException
+     * @return the currency that was set in getInstance() or in setCurrency(),
+     *         or {@code null}.
+     * @throws UnsupportedOperationException
      */
     public Currency getCurrency() {
         throw new UnsupportedOperationException();
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing currency for the
-     * default Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing currency values
+     * for the default locale.
      * 
-     * @return a NumberFormat
+     * @return a {@code NumberFormat} for handling currency values.
      */
     public final static NumberFormat getCurrencyInstance() {
         return getCurrencyInstance(Locale.getDefault());
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing currency for the
-     * specified Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing currency values
+     * for the specified locale.
      * 
      * @param locale
-     *            the Locale
-     * @return a NumberFormat
+     *            the locale to use.
+     * @return a {@code NumberFormat} for handling currency values.
      */
     public static NumberFormat getCurrencyInstance(Locale locale) {
         com.ibm.icu.text.DecimalFormat icuFormat = (com.ibm.icu.text.DecimalFormat) com.ibm.icu.text.NumberFormat
@@ -236,22 +356,22 @@
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing integers for the
-     * default Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing integers for the
+     * default locale.
      * 
-     * @return a NumberFormat
+     * @return a {@code NumberFormat} for handling integers.
      */
     public final static NumberFormat getIntegerInstance() {
         return getIntegerInstance(Locale.getDefault());
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing integers for the
-     * specified Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing integers for
+     * the specified locale.
      * 
      * @param locale
-     *            the Locale
-     * @return a NumberFormat
+     *            the locale to use.
+     * @return a {@code NumberFormat} for handling integers.
      */
     public static NumberFormat getIntegerInstance(Locale locale) {
         com.ibm.icu.text.DecimalFormat icuFormat = (com.ibm.icu.text.DecimalFormat) com.ibm.icu.text.NumberFormat
@@ -264,86 +384,86 @@
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing numbers for the default
-     * Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing numbers for the
+     * default locale.
      * 
-     * @return a NumberFormat
+     * @return a {@code NumberFormat} for handling {@code Number} objects.
      */
     public final static NumberFormat getInstance() {
         return getNumberInstance();
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing numbers for the
-     * specified Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing numbers for the
+     * specified locale.
      * 
      * @param locale
-     *            the Locale
-     * @return a NumberFormat
+     *            the locale to use.
+     * @return a {@code NumberFormat} for handling {@code Number} objects.
      */
     public static NumberFormat getInstance(Locale locale) {
         return getNumberInstance(locale);
     }
 
     /**
-     * Answers the maximum number of fraction digits that are printed when
+     * Returns 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.
      * 
-     * @return the maximum number of fraction digits
+     * @return the maximum number of fraction digits.
      */
     public int getMaximumFractionDigits() {
         return maximumFractionDigits;
     }
 
     /**
-     * Answers the maximum number of integer digits that are printed when
+     * Returns 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.
      * 
-     * @return the maximum number of integer digits
+     * @return the maximum number of integer digits.
      */
     public int getMaximumIntegerDigits() {
         return maximumIntegerDigits;
     }
 
     /**
-     * Answers the minimum number of fraction digits that are printed when
+     * Returns the minimum number of fraction digits that are printed when
      * formatting.
      * 
-     * @return the minimum number of fraction digits
+     * @return the minimum number of fraction digits.
      */
     public int getMinimumFractionDigits() {
         return minimumFractionDigits;
     }
 
     /**
-     * Answers the minimum number of integer digits that are printed when
+     * Returns the minimum number of integer digits that are printed when
      * formatting.
      * 
-     * @return the minimum number of integer digits
+     * @return the minimum number of integer digits.
      */
     public int getMinimumIntegerDigits() {
         return minimumIntegerDigits;
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing numbers for the default
-     * Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing numbers for the
+     * default locale.
      * 
-     * @return a NumberFormat
+     * @return a {@code NumberFormat} for handling {@code Number} objects.
      */
     public final static NumberFormat getNumberInstance() {
         return getNumberInstance(Locale.getDefault());
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing numbers for the
-     * specified Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing numbers for the
+     * specified locale.
      * 
      * @param locale
-     *            the Locale
-     * @return a NumberFormat
+     *            the locale to use.
+     * @return a {@code NumberFormat} for handling {@code Number} objects.
      */
     public static NumberFormat getNumberInstance(Locale locale) {
         com.ibm.icu.text.DecimalFormat icuFormat = (com.ibm.icu.text.DecimalFormat) com.ibm.icu.text.NumberFormat
@@ -353,22 +473,22 @@
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing percentages for the
-     * default Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing percentage
+     * values for the default locale.
      * 
-     * @return a NumberFormat
+     * @return a {@code NumberFormat} for handling percentage values.
      */
     public final static NumberFormat getPercentInstance() {
         return getPercentInstance(Locale.getDefault());
     }
 
     /**
-     * Answers a NumberFormat for formatting and parsing percentages for the
-     * specified Locale.
+     * Returns a {@code NumberFormat} for formatting and parsing percentage
+     * values for the specified locale.
      * 
      * @param locale
-     *            the Locale
-     * @return a NumberFormat
+     *            the locale to use.
+     * @return a {@code NumberFormat} for handling percentage values.
      */
     public static NumberFormat getPercentInstance(Locale locale) {
         com.ibm.icu.text.DecimalFormat icuFormat = (com.ibm.icu.text.DecimalFormat) com.ibm.icu.text.NumberFormat
@@ -377,14 +497,6 @@
         return new DecimalFormat(pattern, new DecimalFormatSymbols(locale));
     }
 
-    /**
-     * 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 (groupingUsed ? 1231 : 1237) + (parseIntegerOnly ? 1231 : 1237)
@@ -393,36 +505,36 @@
     }
 
     /**
-     * Answers whether this NumberFormat formats and parses numbers using a
+     * Indicates whether this number format formats and parses numbers using a
      * grouping separator.
      * 
-     * @return true when a grouping separator is used, false otherwise
+     * @return {@code true} if a grouping separator is used; {@code false}
+     *         otherwise.
      */
     public boolean isGroupingUsed() {
         return groupingUsed;
     }
 
     /**
-     * Answers whether this NumberFormat only parses integer numbers. Parsing
+     * Indicates whether this number format only parses integer numbers. Parsing
      * stops if a decimal separator is encountered.
      * 
-     * @return true if this NumberFormat only parses integers, false for parsing
-     *         integers or fractions
+     * @return {@code true} if this number format only parses integers,
+     *         {@code false} if if parsese integers as well as fractions.
      */
     public boolean isParseIntegerOnly() {
         return parseIntegerOnly;
     }
 
     /**
-     * Parse a Number from the specified String using the rules of this
-     * NumberFormat.
+     * Parses a {@code Number} from the specified string using the rules of this
+     * number format.
      * 
      * @param string
-     *            the String to parse
-     * @return the Number resulting from the parse
-     * 
-     * @exception ParseException
-     *                when an error occurs during parsing
+     *            the string to parse.
+     * @return the {@code Number} resulting from the parsing.
+     * @throws ParseException
+     *            if an error occurs during parsing.
      */
     public Number parse(String string) throws ParseException {
         ParsePosition pos = new ParsePosition(0);
@@ -434,33 +546,25 @@
     }
 
     /**
-     * Parse a Number 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 Number} 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 the Number 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 {@code Number} resulting from the parse or {@code null} if
+     *         there is an error.
      */
     public abstract Number parse(String string, ParsePosition position);
 
-    /**
-     * Parse a Number 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.
-     * 
-     * @param string
-     *            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 Number resulting from the parse, or null if there is an error
-     */
     @Override
     public final Object parseObject(String string, ParsePosition position) {
         if (position == null) {
@@ -477,28 +581,27 @@
 
     /**
      * Sets the currency used by this number format when formatting currency
-     * values.
-     * <p>
-     * The min and max fraction digits remain the same.
+     * values. The min and max fraction digits remain the same.
      * <p>
-     * This implementation throws UnsupportedOperationException, concrete sub
-     * classes should override if they support currency formatting.
-     * <p>
-     * 
+     * This implementation throws {@code UnsupportedOperationException},
+     * concrete subclasses should override this method if they support currency
+     * formatting.
+     *
      * @param currency
-     *            the new Currency
-     * @throws java.lang.UnsupportedOperationException
+     *            the new currency.
+     * @throws UnsupportedOperationException
      */
     public void setCurrency(Currency currency) {
         throw new UnsupportedOperationException();
     }
 
     /**
-     * Sets whether this NumberFormat formats and parses numbers using a
+     * Sets whether this number format formats and parses numbers using a
      * grouping separator.
      * 
      * @param value
-     *            true when a grouping separator is used, false otherwise
+     *            {@code true} if a grouping separator is used; {@code false}
+     *            otherwise.
      */
     public void setGroupingUsed(boolean value) {
         groupingUsed = value;
@@ -510,7 +613,7 @@
      * the least significant digits are truncated.
      * 
      * @param value
-     *            the maximum number of fraction digits
+     *            the maximum number of fraction digits.
      */
     public void setMaximumFractionDigits(int value) {
         maximumFractionDigits = value < 0 ? 0 : value;
@@ -520,12 +623,12 @@
     }
 
     /**
-     * Used to specify the new maximum count 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.
+     * Sets the new maximum count 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.
      * 
      * @param value
-     *            the new maximum number of integer numerals for display
+     *            the new maximum number of integer numerals for display.
      */
     public void setMaximumIntegerDigits(int value) {
         maximumIntegerDigits = value < 0 ? 0 : value;
@@ -539,7 +642,7 @@
      * formatting.
      * 
      * @param value
-     *            the minimum number of fraction digits
+     *            the minimum number of fraction digits.
      */
     public void setMinimumFractionDigits(int value) {
         minimumFractionDigits = value < 0 ? 0 : value;
@@ -553,7 +656,7 @@
      * formatting.
      * 
      * @param value
-     *            the minimum number of integer digits
+     *            the minimum number of integer digits.
      */
     public void setMinimumIntegerDigits(int value) {
         minimumIntegerDigits = value < 0 ? 0 : value;
@@ -563,14 +666,14 @@
     }
 
     /**
-     * Specifies if this NumberFormat should only parse numbers as integers or
-     * else as any kind of number. If this is called with a <code>true</code>
+     * Specifies if this number format should parse numbers only as integers or
+     * else as any kind of number. If this method is called with a {@code true}
      * value then subsequent parsing attempts will stop if a decimal separator
      * is encountered.
      * 
      * @param value
-     *            <code>true</code> to only parse integers, <code>false</code>
-     *            to parse integers and fractions
+     *            {@code true} to only parse integers, {@code false} to parse
+     *            integers as well as fractions.
      */
     public void setParseIntegerOnly(boolean value) {
         parseIntegerOnly = value;
@@ -651,10 +754,10 @@
 
     /**
      * The instances of this inner class are used as attribute keys and values
-     * in AttributedCharacterIterator that
-     * NumberFormat.formatToCharacterIterator() method returns.
+     * in {@code AttributedCharacterIterator} that the
+     * {@link NumberFormat#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>
      */
@@ -662,41 +765,81 @@
 
         private static final long serialVersionUID = 7494728892700160890L;
 
+        /**
+         * This constant stands for the number sign.
+         */
         public static final Field SIGN = new Field("sign"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the integer part of the number.
+         */
         public static final Field INTEGER = new Field("integer"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the fraction part of the number.
+         */
         public static final Field FRACTION = new Field("fraction"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the exponent part of the number.
+         */
         public static final Field EXPONENT = new Field("exponent"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the exponent sign symbol.
+         */
         public static final Field EXPONENT_SIGN = new Field("exponent sign"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the exponent symbol.
+         */
         public static final Field EXPONENT_SYMBOL = new Field("exponent symbol"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the decimal separator.
+         */
         public static final Field DECIMAL_SEPARATOR = new Field(
                 "decimal separator"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the grouping separator.
+         */
         public static final Field GROUPING_SEPARATOR = new Field(
                 "grouping separator"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the percent symbol.
+         */
         public static final Field PERCENT = new Field("percent"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the permille symbol.
+         */
         public static final Field PERMILLE = new Field("per mille"); //$NON-NLS-1$
 
+        /**
+         * This constant stands for the currency symbol.
+         */
         public static final Field CURRENCY = new Field("currency"); //$NON-NLS-1$
 
         /**
-         * Constructs a new instance of NumberFormat.Field with the given field
-         * name.
+         * Constructs a new instance of {@code NumberFormat.Field} with the
+         * given field name.
+         *
+         * @param fieldName
+         *            the field name.
          */
         protected Field(String fieldName) {
             super(fieldName);
         }
 
         /**
-         * serialization method resolve instances to the constant
-         * NumberFormat.Field values
+         * Resolves instances that are deserialized to the constant
+         * {@code NumberFormat.Field} values.
+         *
+         * @return the resolved field object.
+         * @throws InvalidObjectException
+         *             if an error occurs while resolving the field object.
          */
         @Override
         protected Object readResolve() throws InvalidObjectException {

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParseException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParseException.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParseException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParseException.java Thu May  7 08:42:00 2009
@@ -18,8 +18,7 @@
 package java.text;
 
 /**
- * A ParseException is thrown when the String being parsed is not in the correct
- * form.
+ * Thrown when the string being parsed is not in the correct form.
  */
 public class ParseException extends Exception {
 
@@ -28,13 +27,13 @@
     private int errorOffset;
 
     /**
-     * Constructs a new instance of this class with its walkback, message and
-     * the location of the error filled in.
+     * Constructs a new instance of this class with its stack trace, detail
+     * message and the location of the error filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      * @param location
-     *            int The index at which the parse exception occurred.
+     *            the index at which the parse exception occurred.
      */
     public ParseException(String detailMessage, int location) {
         super(detailMessage);
@@ -42,9 +41,9 @@
     }
 
     /**
-     * Answers the index at which the parse exception occurred.
+     * Returns the index at which this parse exception occurred.
      * 
-     * @return int The index of the parse exception.
+     * @return the location of this exception in the parsed string.
      */
     public int getErrorOffset() {
         return errorOffset;

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParsePosition.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParsePosition.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParsePosition.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/ParsePosition.java Thu May  7 08:42:00 2009
@@ -18,32 +18,34 @@
 package java.text;
 
 /**
- * ParsePosition is used to track the current position in a String being parsed.
+ * Tracks the current position in a parsed string. In case of an error the error
+ * index can be set to the position where the error occurred without having to
+ * change the parse position.
  */
 public class ParsePosition {
 
     private int currentPosition, errorIndex = -1;
 
     /**
-     * Constructs a new ParsePosition at the specified index.
+     * Constructs a new {@code ParsePosition} with the specified index.
      * 
      * @param index
-     *            the index to begin parsing
+     *            the index to begin parsing.
      */
     public ParsePosition(int index) {
         currentPosition = index;
     }
 
     /**
-     * Compares the specified object to this ParsePosition and answer if they
-     * are equal. The object must be an instance of ParsePosition and have the
-     * same index and error index.
+     * Compares the specified object to this {@code ParsePosition} and indicates
+     * if they are equal. In order to be equal, {@code object} must be an
+     * instance of {@code ParsePosition} and it must have the same index and
+     * error index.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this ParsePosition,
-     *         false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code ParsePosition}; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -57,31 +59,23 @@
     }
 
     /**
-     * Answers the index at which the parse could not continue.
+     * Returns the index at which the parse could not continue.
      * 
-     * @return the index of the parse error, or -1 if there is no error
+     * @return the index of the parse error or -1 if there is no error.
      */
     public int getErrorIndex() {
         return errorIndex;
     }
 
     /**
-     * Answers the current parse position.
+     * Returns the current parse position.
      * 
-     * @return the current position
+     * @return the current position.
      */
     public int getIndex() {
         return currentPosition;
     }
 
-    /**
-     * 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 currentPosition + errorIndex;
@@ -91,7 +85,7 @@
      * Sets the index at which the parse could not continue.
      * 
      * @param index
-     *            the index of the parse error
+     *            the index of the parse error.
      */
     public void setErrorIndex(int index) {
         errorIndex = index;
@@ -101,16 +95,16 @@
      * Sets the current parse position.
      * 
      * @param index
-     *            the current parse position
+     *            the current parse position.
      */
     public void setIndex(int index) {
         currentPosition = index;
     }
 
     /**
-     * Answers the string representation of this FieldPosition.
+     * Returns the string representation of this parse position.
      * 
-     * @return the string representation of this FieldPosition
+     * @return the string representation of this parse position.
      */
     @Override
     public String toString() {



Mime
View raw message