From fb6815fc9daa43cbdf877b9a7963df323348506f Mon Sep 17 00:00:00 2001
From: Doug Felt <dougfelt@gmail.com>
Date: Thu, 7 Jan 2010 01:18:16 +0000
Subject: [PATCH] ICU-4264 clean up message format docs a bit to clarify use of
 RBNF, shorten long lines

X-SVN-Rev: 27158
---
 .../src/com/ibm/icu/text/MessageFormat.java   | 98 ++++++++++++-------
 1 file changed, 61 insertions(+), 37 deletions(-)

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/text/MessageFormat.java b/icu4j/main/classes/core/src/com/ibm/icu/text/MessageFormat.java
index db381130744..72d7b84f2de 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/text/MessageFormat.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/text/MessageFormat.java
@@ -1,6 +1,6 @@
 /*
 **********************************************************************
-* Copyright (c) 2004-2009, International Business Machines
+* Copyright (c) 2004-2010, International Business Machines
 * Corporation and others.  All Rights Reserved.
 **********************************************************************
 * Author: Alan Liu
@@ -109,7 +109,7 @@ import com.ibm.icu.util.ULocale;
  *         [:ID_START:][:ID_CONTINUE:]*
  *
  * <i>FormatType: one of </i>
- *         number date time choice
+ *         number date time choice spellout ordinal duration plural
  *
  * <i>FormatStyle:</i>
  *         short
@@ -120,6 +120,7 @@ import com.ibm.icu.util.ULocale;
  *         currency
  *         percent
  *         <i>SubformatPattern</i>
+ *         <i>RulesetName</i>
  *
  * <i>String:</i>
  *         <i>StringPart<sub>opt</sub></i>
@@ -139,6 +140,8 @@ import com.ibm.icu.util.ULocale;
  *         <i>UnquotedPattern</i>
  * </pre></blockquote>
  *
+ * <i>RulesetName:</i>
+ *         <i>UnquotedString</i>
  * <p>
  * Within a <i>String</i>, <code>"''"</code> represents a single
  * quote. A <i>QuotedString</i> can contain arbitrary characters
@@ -255,16 +258,19 @@ import com.ibm.icu.util.ULocale;
  *       <td><code>new ChoiceFormat(subformatPattern)</code>
  *    <tr>
  *       <td><code>spellout</code>
- *       <td><i>Ruleset name (optional)</i>
- *       <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.SPELLOUT)<br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
+ *       <td><i>RulesetName (optional)</i>
+ *       <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.SPELLOUT)
+ *           <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
  *    <tr>
  *       <td><code>ordinal</code>
- *       <td><i>Ruleset name (optional)</i>
- *       <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.ORDINAL)<br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
+ *       <td><i>RulesetName (optional)</i>
+ *       <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.ORDINAL)
+ *           <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
  *    <tr>
  *       <td><code>duration</code>
- *       <td><i>Ruleset name (optional)</i>
- *       <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.DURATION)<br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
+ *       <td><i>RulesetName (optional)</i>
+ *       <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.DURATION)
+ *           <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
  *    <tr>
  *       <td><code>plural</code>
  *       <td><i>SubformatPattern</i>
@@ -391,9 +397,6 @@ import com.ibm.icu.util.ULocale;
  * @author       Mark Davis
  * @stable ICU 3.0
  */
- // TODO: Update JavaDoc class description with regards to named arguments.
- // TODO: Update JavaDoc class description with regards to PluralFormat
- //       integration.
 public class MessageFormat extends UFormat implements BaseFormat<Object,StringBuffer,String> {
 
     // Generated by serialver from JDK 1.4.1_01
@@ -588,7 +591,6 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
         this.pattern = segments[0].toString();
     }
 
-
     /**
      * Returns a pattern representing the current state of the message format.
      * The string is constructed from internal information and therefore
@@ -935,7 +937,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
     }
     
     /**
-     * Get the format argument names. For more details, see {@link #setFormatByArgumentName(String, Format)}.
+     * Get the format argument names. For more details, see 
+     * {@link #setFormatByArgumentName(String, Format)}.
      * @return List of names
      * @deprecated This API is ICU internal only.
      * @internal
@@ -949,7 +952,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
     }
     
     /**
-     * Get the formats according to their argument names. For more details, see {@link #setFormatByArgumentName(String, Format)}.
+     * Get the formats according to their argument names. For more details, see 
+     * {@link #setFormatByArgumentName(String, Format)}.
      * @return format associated with the name, or null if there isn't one.
      * @deprecated This API is ICU internal only.
      * @internal
@@ -1006,7 +1010,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
      *    <tr>
      *       <td><code>null</code>
      *       <td><code>instanceof Date</code>
-     *       <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)</code>
+     *       <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, 
+     *           DateFormat.SHORT, getLocale()).format(argument)</code>
      *    <tr>
      *       <td><code>null</code>
      *       <td><code>instanceof String</code>
@@ -1083,7 +1088,9 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
      * Creates a MessageFormat with the given pattern and uses it
      * to format the given arguments. This is equivalent to
      * <blockquote>
-     *     <code>(new {@link #MessageFormat(String) MessageFormat}(pattern)).{@link #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition) format}(arguments, new StringBuffer(), null).toString()</code>
+     *     <code>(new {@link #MessageFormat(String) MessageFormat}(pattern)).{@link 
+     *     #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition) 
+     *     format}(arguments, new StringBuffer(), null).toString()</code>
      * </blockquote>
      *
      * @throws IllegalArgumentException if the pattern is invalid,
@@ -1134,8 +1141,10 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
      * provided <code>StringBuffer</code>.
      * This is equivalent to either of
      * <blockquote>
-     *     <code>{@link #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition) format}((Object[]) arguments, result, pos)</code>
-     *     <code>{@link #format(java.util.Map, java.lang.StringBuffer, java.text.FieldPosition) format}((Map) arguments, result, pos)</code>
+     *     <code>{@link #format(java.lang.Object[], java.lang.StringBuffer, 
+     *     java.text.FieldPosition) format}((Object[]) arguments, result, pos)</code>
+     *     <code>{@link #format(java.util.Map, java.lang.StringBuffer, 
+     *     java.text.FieldPosition) format}((Map) arguments, result, pos)</code>
      * </blockquote>
      * A map must be provided if this format uses named arguments, otherwise
      * an IllegalArgumentException will be thrown.
@@ -1177,7 +1186,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
      * The text of the returned <code>AttributedCharacterIterator</code> is
      * the same that would be returned by
      * <blockquote>
-     *     <code>{@link #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition) format}(arguments, new StringBuffer(), null).toString()</code>
+     *     <code>{@link #format(java.lang.Object[], java.lang.StringBuffer, 
+     *     java.text.FieldPosition) format}(arguments, new StringBuffer(), null).toString()</code>
      * </blockquote>
      * <p>
      * In addition, the <code>AttributedCharacterIterator</code> contains at
@@ -1204,7 +1214,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
     @SuppressWarnings("unchecked")
     public AttributedCharacterIterator formatToCharacterIterator(Object arguments) {
         StringBuffer result = new StringBuffer();
-        ArrayList<AttributedCharacterIterator> iterators = new ArrayList<AttributedCharacterIterator>();
+        ArrayList<AttributedCharacterIterator> iterators = 
+            new ArrayList<AttributedCharacterIterator>();
 
         if (arguments == null) {
             throw new NullPointerException(
@@ -1542,7 +1553,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
          */
         protected Object readResolve() throws InvalidObjectException {
             if (this.getClass() != MessageFormat.Field.class) {
-                throw new InvalidObjectException("A subclass of MessageFormat.Field must implement readResolve.");
+                throw new InvalidObjectException(
+                    "A subclass of MessageFormat.Field must implement readResolve.");
             }
             if (this.getName().equals(ARGUMENT.getName())) {
                 return ARGUMENT;
@@ -1650,7 +1662,7 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
      *            expected by the format element(s) that use it.
      */
     private StringBuffer subformat(Object[] arguments, StringBuffer result,
-                                   FieldPosition fp, List<AttributedCharacterIterator> characterIterators) {
+        FieldPosition fp,  List<AttributedCharacterIterator> characterIterators) {
         return subformat(arrayToMap(arguments), result, fp, characterIterators);
     }
 
@@ -1662,7 +1674,7 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
      *         expected by the format element(s) that use it.
      */
     private StringBuffer subformat(Map<String, Object> arguments, StringBuffer result,
-                                   FieldPosition fp, List<AttributedCharacterIterator> characterIterators) {
+        FieldPosition fp, List<AttributedCharacterIterator> characterIterators) {
         // note: this implementation assumes a fast substring & index.
         // if this is not true, would be better to append chars one by one.
         int lastOffset = 0;
@@ -1735,9 +1747,11 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
                         append(result, subIterator);
                         if (last != result.length()) {
                             characterIterators.add(
-                                         _createAttributedCharacterIterator(
-                                         subIterator, Field.ARGUMENT,
-                                         argumentNamesAreNumeric ? (Object)new Integer(argumentName) : (Object)argumentName));
+                                _createAttributedCharacterIterator(
+                                subIterator, Field.ARGUMENT,
+                                argumentNamesAreNumeric ? 
+                                    (Object)new Integer(argumentName) : 
+                                    (Object)argumentName));
                             last = result.length();
                         }
                         arg = null;
@@ -1745,9 +1759,11 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
                     if (arg != null && arg.length() > 0) {
                         result.append(arg);
                         characterIterators.add(
-                                 _createAttributedCharacterIterator(
-                                 arg, Field.ARGUMENT,
-                                 argumentNamesAreNumeric ? (Object)new Integer(argumentName) : (Object)argumentName));
+                            _createAttributedCharacterIterator(
+                                arg, Field.ARGUMENT,
+                                argumentNamesAreNumeric ? 
+                                    (Object)new Integer(argumentName) : 
+                                    (Object)argumentName));
                         last = result.length();
                     }
                 } else {
@@ -1900,7 +1916,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
                 newFormat = NumberFormat.getIntegerInstance(ulocale);
                 break;
             default: // pattern
-                newFormat = new DecimalFormat(segments[3].toString(), new DecimalFormatSymbols(ulocale));
+                newFormat = new DecimalFormat(segments[3].toString(), 
+                        new DecimalFormatSymbols(ulocale));
                 break;
             }
             break;
@@ -1958,7 +1975,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
             break;
         case TYPE_SPELLOUT:
             {
-                RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, RuleBasedNumberFormat.SPELLOUT);
+                RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, 
+                        RuleBasedNumberFormat.SPELLOUT);
                 String ruleset = segments[3].toString().trim();
                 if (ruleset.length() != 0) {
                     try {
@@ -1973,7 +1991,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
             break;
         case TYPE_ORDINAL:
             {
-                RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, RuleBasedNumberFormat.ORDINAL);
+                RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, 
+                        RuleBasedNumberFormat.ORDINAL);
                 String ruleset = segments[3].toString().trim();
                 if (ruleset.length() != 0) {
                     try {
@@ -1988,7 +2007,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
             break;
         case TYPE_DURATION:
             {
-                RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, RuleBasedNumberFormat.DURATION);
+                RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, 
+                        RuleBasedNumberFormat.DURATION);
                 String ruleset = segments[3].toString().trim();
                 if (ruleset.length() != 0) {
                     try {
@@ -2048,7 +2068,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
         return -1;
     }
 
-    private static final void copyAndFixQuotes(String source, int start, int end, StringBuffer target) {
+    private static final void copyAndFixQuotes(String source, int start, int end, 
+            StringBuffer target) {
         // added 'gotLB' logic from ICU4C - questionable [alan]
         boolean gotLB = false;
         for (int i = start; i < end; ++i) {
@@ -2101,7 +2122,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
             }
         }
         if (!isValid) {
-            throw new InvalidObjectException("Could not reconstruct MessageFormat from corrupt stream.");
+            throw new InvalidObjectException(
+                "Could not reconstruct MessageFormat from corrupt stream.");
         }
         if (ulocale == null) {
             ulocale = ULocale.forLocale(locale);
@@ -2246,7 +2268,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
         return as.getIterator();
     }
 
-    private static AttributedCharacterIterator _createAttributedCharacterIterator(AttributedCharacterIterator[] iterators) {
+    private static AttributedCharacterIterator _createAttributedCharacterIterator(
+            AttributedCharacterIterator[] iterators) {
         if (iterators == null || iterators.length == 0) {
             return _createAttributedCharacterIterator("");
         }
@@ -2287,7 +2310,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
         return as.getIterator();
     }
 
-    private static AttributedCharacterIterator _createAttributedCharacterIterator(AttributedCharacterIterator iterator,
+    private static AttributedCharacterIterator _createAttributedCharacterIterator(
+            AttributedCharacterIterator iterator,
             AttributedCharacterIterator.Attribute key, Object value) {
         AttributedString as = new AttributedString(iterator);
         as.addAttribute(key, value);