Improve documentation about the user's default locale.

Add a bit of text to Locale's class documentation, and include a link from
every method that uses Locale.getDefault(). Also try to consistently say
"user's default locale", as a subliminal hint that this isn't necessarily
the developer's locale, nor en_US.

Bug: 2593000
Change-Id: Ieebe864ed6b9fecbfef5d5415269299739cedd1b

9 files changed, 59 insertions, 96 deletions

diff --git a/text/src/main/java/java/text/BreakIterator.java b/text/src/main/java/java/text/BreakIterator.java
index 901f5ab..f14f728 100644
--- a/text/src/main/java/java/text/BreakIterator.java
+++ b/text/src/main/java/java/text/BreakIterator.java
@@ -258,8 +258,8 @@ public abstract class BreakIterator implements Cloneable {
 
     /**
      * Returns a new instance of {@code BreakIterator} to iterate over
-     * characters using the default locale.
-     * 
+     * characters using the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getCharacterInstance() {
@@ -280,8 +280,8 @@ public abstract class BreakIterator implements Cloneable {
 
     /**
      * Returns a new instance of {{@code BreakIterator} to iterate over
-     * line breaks using the default locale.
-     * 
+     * line breaks using the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getLineInstance() {
@@ -304,7 +304,7 @@ public abstract class BreakIterator implements Cloneable {
     /**
      * Returns a new instance of {@code BreakIterator} to iterate over
      * sentence-breaks using the default locale.
-     * 
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getSentenceInstance() {
@@ -327,7 +327,7 @@ public abstract class BreakIterator implements Cloneable {
     /**
      * Returns a new instance of {@code BreakIterator} to iterate over
      * word-breaks using the default locale.
-     * 
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @return a new instance of {@code BreakIterator} using the default locale.
      */
     public static BreakIterator getWordInstance() {
diff --git a/text/src/main/java/java/text/Collator.java b/text/src/main/java/java/text/Collator.java
index fca464d..902eecc 100644
--- a/text/src/main/java/java/text/Collator.java
+++ b/text/src/main/java/java/text/Collator.java
@@ -279,22 +279,16 @@ public abstract class Collator implements Comparator<Object>, Cloneable {
     }
 
     /**
-     * Returns a {@code Collator} instance which is appropriate for the default
+     * Returns a {@code Collator} instance which is appropriate for the user's default
      * {@code Locale}.
-     * 
-     * @return the collator for the default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      */
     public static Collator getInstance() {
         return getInstance(Locale.getDefault());
     }
 
     /**
-     * Returns a {@code Collator} instance which is appropriate for the
-     * specified {@code Locale}.
-     * 
-     * @param locale
-     *            the locale.
-     * @return the collator for {@code locale}.
+     * Returns a {@code Collator} instance which is appropriate for {@code locale}.
      */
     public static Collator getInstance(Locale locale) {
         // BEGIN android-changed: removed non-functional cache.
@@ -312,14 +306,6 @@ public abstract class Collator implements Comparator<Object>, Cloneable {
         return strength_ICU_Java(this.icuColl.getStrength());
     }
 
-    /**
-     * Returns an integer hash code for this collator.
-     * 
-     * @return this collator's hash code.
-     * 
-     * @see #equals(Object)
-     * @see #equals(String, String)
-     */
     @Override
     public abstract int hashCode();
 
diff --git a/text/src/main/java/java/text/DateFormat.java b/text/src/main/java/java/text/DateFormat.java
index 055cbc3..0beaac1 100644
--- a/text/src/main/java/java/text/DateFormat.java
+++ b/text/src/main/java/java/text/DateFormat.java
@@ -431,8 +431,8 @@ public abstract class DateFormat extends Format {
 
     /**
      * Returns a {@code DateFormat} instance for formatting and parsing dates in
-     * the specified style for the default locale.
-     * 
+     * the specified style for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @param style
      *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @return the {@code DateFormat} instance for {@code style} and the default
@@ -480,8 +480,8 @@ public abstract class DateFormat extends Format {
 
     /**
      * Returns a {@code DateFormat} instance for formatting and parsing of both
-     * dates and time values in the manner appropriate for the default locale.
-     * 
+     * dates and time values in the manner appropriate for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @param dateStyle
      *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @param timeStyle
@@ -492,8 +492,7 @@ public abstract class DateFormat extends Format {
      *             if {@code dateStyle} or {@code timeStyle} is not one of
      *             SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      */
-    public final static DateFormat getDateTimeInstance(int dateStyle,
-            int timeStyle) {
+    public final static DateFormat getDateTimeInstance(int dateStyle, int timeStyle) {
         checkTimeStyle(timeStyle);
         checkDateStyle(dateStyle);
         return getDateTimeInstance(dateStyle, timeStyle, Locale.getDefault());
@@ -558,8 +557,8 @@ public abstract class DateFormat extends Format {
 
     /**
      * Returns a {@code DateFormat} instance for formatting and parsing time
-     * values in the specified style for the default locale.
-     * 
+     * values in the specified style for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @param style
      *            one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
      * @return the {@code DateFormat} instance for {@code style} and the default
diff --git a/text/src/main/java/java/text/DateFormatSymbols.java b/text/src/main/java/java/text/DateFormatSymbols.java
index f702716..73e89e0 100644
--- a/text/src/main/java/java/text/DateFormatSymbols.java
+++ b/text/src/main/java/java/text/DateFormatSymbols.java
@@ -102,7 +102,8 @@ public class DateFormatSymbols implements Serializable, Cloneable {
 
     /**
      * Constructs a new {@code DateFormatSymbols} instance containing the
-     * symbols for the default locale.
+     * symbols for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      */
     public DateFormatSymbols() {
         this(Locale.getDefault());
@@ -130,8 +131,9 @@ public class DateFormatSymbols implements Serializable, Cloneable {
     }
 
     /**
-     * Returns a new {@code DateFormatSymbols} instance for the default locale.
-     *
+     * Returns a new {@code DateFormatSymbols} instance for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @return an instance of {@code DateFormatSymbols}
      * @since 1.6
      * @hide
diff --git a/text/src/main/java/java/text/DecimalFormat.java b/text/src/main/java/java/text/DecimalFormat.java
index e33d407..2776575 100644
--- a/text/src/main/java/java/text/DecimalFormat.java
+++ b/text/src/main/java/java/text/DecimalFormat.java
@@ -554,7 +554,8 @@ public class DecimalFormat extends NumberFormat {
 
     /**
      * Constructs a new {@code DecimalFormat} for formatting and parsing numbers
-     * for the default locale.
+     * for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      */
     public DecimalFormat() {
         // BEGIN android-changed: reduce duplication.
@@ -567,8 +568,8 @@ public class DecimalFormat extends NumberFormat {
 
     /**
      * Constructs a new {@code DecimalFormat} using the specified non-localized
-     * pattern and the {@code DecimalFormatSymbols} for the default Locale.
-     * 
+     * pattern and the {@code DecimalFormatSymbols} for the user's default Locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @param pattern
      *            the non-localized pattern.
      * @throws IllegalArgumentException
diff --git a/text/src/main/java/java/text/DecimalFormatSymbols.java b/text/src/main/java/java/text/DecimalFormatSymbols.java
index 0ee705c..7188745 100644
--- a/text/src/main/java/java/text/DecimalFormatSymbols.java
+++ b/text/src/main/java/java/text/DecimalFormatSymbols.java
@@ -65,7 +65,9 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
 
     /**
      * Constructs a new {@code DecimalFormatSymbols} containing the symbols for
-     * the default locale. Best practice is to create a {@code DecimalFormat}
+     * the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * Best practice is to create a {@code DecimalFormat}
      * and then to get the {@code DecimalFormatSymbols} from that object by
      * calling {@link DecimalFormat#getDecimalFormatSymbols()}.
      */
@@ -75,7 +77,9 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
 
     /**
      * Constructs a new DecimalFormatSymbols containing the symbols for the
-     * specified Locale. Best practice is to create a {@code DecimalFormat}
+     * specified Locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * Best practice is to create a {@code DecimalFormat}
      * and then to get the {@code DecimalFormatSymbols} from that object by
      * calling {@link DecimalFormat#getDecimalFormatSymbols()}.
      * 
@@ -103,8 +107,9 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
     }
 
     /**
-     * Returns a new {@code DecimalFormatSymbols} instance for the default locale.
-     *
+     * Returns a new {@code DecimalFormatSymbols} instance for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @return an instance of {@code DecimalFormatSymbols}
      * @since 1.6
      * @hide
diff --git a/text/src/main/java/java/text/MessageFormat.java b/text/src/main/java/java/text/MessageFormat.java
index 4dc684d..1f3d24f 100644
--- a/text/src/main/java/java/text/MessageFormat.java
+++ b/text/src/main/java/java/text/MessageFormat.java
@@ -42,8 +42,8 @@ import org.apache.harmony.text.internal.nls.Messages;
  * {@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
+ * {@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>
@@ -338,7 +338,7 @@ public class MessageFormat extends Format {
 
     private static final long serialVersionUID = 6479157306784022952L;
 
-    private Locale locale = Locale.getDefault();
+    private Locale locale;
 
     transient private String[] strings;
 
@@ -351,8 +351,7 @@ public class MessageFormat extends Format {
     transient private int maxArgumentIndex;
 
     /**
-     * Constructs a new {@code MessageFormat} using the specified pattern and
-     * the specified locale for formats.
+     * Constructs a new {@code MessageFormat} using the specified pattern and {@code locale}.
      * 
      * @param template
      *            the pattern.
@@ -368,7 +367,8 @@ public class MessageFormat extends Format {
 
     /**
      * Constructs a new {@code MessageFormat} using the specified pattern and
-     * the default locale for formats.
+     * the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * 
      * @param template
      *            the pattern.
@@ -376,7 +376,7 @@ public class MessageFormat extends Format {
      *            if the pattern cannot be parsed.
      */
     public MessageFormat(String template) {
-        applyPattern(template);
+        this(template, Locale.getDefault());
     }
 
     /**
diff --git a/text/src/main/java/java/text/NumberFormat.java b/text/src/main/java/java/text/NumberFormat.java
index 2d0c6c5..52788bd 100644
--- a/text/src/main/java/java/text/NumberFormat.java
+++ b/text/src/main/java/java/text/NumberFormat.java
@@ -336,7 +336,8 @@ public abstract class NumberFormat extends Format {
 
     /**
      * Returns a {@code NumberFormat} for formatting and parsing currency values
-     * for the default locale.
+     * for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * 
      * @return a {@code NumberFormat} for handling currency values.
      */
@@ -361,7 +362,8 @@ public abstract class NumberFormat extends Format {
 
     /**
      * Returns a {@code NumberFormat} for formatting and parsing integers for the
-     * default locale.
+     * user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * 
      * @return a {@code NumberFormat} for handling integers.
      */
@@ -458,7 +460,8 @@ public abstract class NumberFormat extends Format {
 
     /**
      * Returns a {@code NumberFormat} for formatting and parsing numbers for the
-     * default locale.
+     * user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * 
      * @return a {@code NumberFormat} for handling {@code Number} objects.
      */
@@ -483,7 +486,8 @@ public abstract class NumberFormat extends Format {
 
     /**
      * Returns a {@code NumberFormat} for formatting and parsing percentage
-     * values for the default locale.
+     * values for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * 
      * @return a {@code NumberFormat} for handling percentage values.
      */
diff --git a/text/src/main/java/java/text/SimpleDateFormat.java b/text/src/main/java/java/text/SimpleDateFormat.java
index d5c06fe..6057b23 100644
--- a/text/src/main/java/java/text/SimpleDateFormat.java
+++ b/text/src/main/java/java/text/SimpleDateFormat.java
@@ -312,9 +312,7 @@ public class SimpleDateFormat extends DateFormat {
 
     private static final long serialVersionUID = 4774881970558875024L;
 
-    // BEGIN android-changed
-    static final String patternChars = "GyMdkHmsSEDFwWahKzZ"; //$NON-NLS-1$
-    // END android-changed
+    static final String patternChars = "GyMdkHmsSEDFwWahKzZ";
 
     private String pattern;
 
@@ -324,28 +322,22 @@ public class SimpleDateFormat extends DateFormat {
 
     private Date defaultCenturyStart;
 
-    // BEGIN android-removed
-    // private transient String tzId;
-    //
-    // private transient com.ibm.icu.text.SimpleDateFormat icuFormat;
-    // END android-removed
-
     /**
      * Constructs a new {@code SimpleDateFormat} for formatting and parsing
-     * dates and times in the {@code SHORT} style for the default locale.
+     * dates and times in the {@code SHORT} style for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      */
     public SimpleDateFormat() {
         this(Locale.getDefault());
-        // BEGIN android-changed
-        pattern = defaultPattern();
-        // END android-changed
-        formatData = new DateFormatSymbols(Locale.getDefault());
+        this.pattern = defaultPattern();
+        this.formatData = new DateFormatSymbols(Locale.getDefault());
     }
 
     /**
      * Constructs a new {@code SimpleDateFormat} using the specified
      * non-localized pattern and the {@code DateFormatSymbols} and {@code
-     * Calendar} for the default locale.
+     * Calendar} for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * 
      * @param pattern
      *            the pattern.
@@ -441,8 +433,9 @@ public class SimpleDateFormat extends DateFormat {
     /**
      * Constructs a new {@code SimpleDateFormat} using the specified
      * non-localized pattern and {@code DateFormatSymbols} and the {@code
-     * Calendar} for the default locale.
-     *
+     * Calendar} for the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param template
      *            the pattern.
      * @param value
@@ -455,27 +448,10 @@ public class SimpleDateFormat extends DateFormat {
     public SimpleDateFormat(String template, DateFormatSymbols value) {
         this(Locale.getDefault());
         validatePattern(template);
-        // BEGIN android-removed
-        // icuFormat = new com.ibm.icu.text.SimpleDateFormat(template, Locale.getDefault());
-        // icuFormat.setTimeZone(com.ibm.icu.util.TimeZone.getTimeZone(tzId));
-        // END android-removed
         pattern = template;
         formatData = (DateFormatSymbols) value.clone();
     }
 
-    // BEGIN android-removed
-    // private void copySymbols(DateFormatSymbols value, com.ibm.icu.text.DateFormatSymbols icuSymbols) {
-    //     icuSymbols.setAmPmStrings(value.getAmPmStrings());
-    //     icuSymbols.setEras(value.getEras());
-    //     icuSymbols.setLocalPatternChars(value.getLocalPatternChars());
-    //     icuSymbols.setMonths(value.getMonths());
-    //     icuSymbols.setShortMonths(value.getShortMonths());
-    //     icuSymbols.setShortWeekdays(value.getShortWeekdays());
-    //     icuSymbols.setWeekdays(value.getWeekdays());
-    //     icuSymbols.setZoneStrings(value.getZoneStrings());
-    // }
-    // END android-removed
-
     /**
      * Constructs a new {@code SimpleDateFormat} using the specified
      * non-localized pattern and the {@code DateFormatSymbols} and {@code
@@ -503,11 +479,6 @@ public class SimpleDateFormat extends DateFormat {
         // END android-changed
     }
 
-    // BEGIN android-removed
-    // SimpleDateFormat(Locale locale, com.ibm.icu.text.SimpleDateFormat icuFormat){
-    // }
-    // END android-removed
-    
     private SimpleDateFormat(Locale locale) {
         numberFormat = NumberFormat.getInstance(locale);
         numberFormat.setParseIntegerOnly(true);
@@ -602,18 +573,13 @@ public class SimpleDateFormat extends DateFormat {
         SimpleDateFormat clone = (SimpleDateFormat) super.clone();
         clone.formatData = (DateFormatSymbols) formatData.clone();
         clone.defaultCenturyStart = new Date(defaultCenturyStart.getTime());
-        // BEGIN android-removed
-        // clone.tzId = tzId;
-        // END android-removed
         return clone;
     }
 
-    // BEGIN android-added
     private static String defaultPattern() {
         LocaleData localeData = com.ibm.icu4jni.util.Resources.getLocaleData(Locale.getDefault());
         return localeData.getDateFormat(SHORT) + " " + localeData.getTimeFormat(SHORT);
     }
-    // END android-added
 
     /**
      * Compares the specified object with this simple date format and indicates