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

7 files changed, 104 insertions, 118 deletions

diff --git a/luni/src/main/java/java/io/PrintStream.java b/luni/src/main/java/java/io/PrintStream.java
index 9e84342..ced2a7f 100644
--- a/luni/src/main/java/java/io/PrintStream.java
+++ b/luni/src/main/java/java/io/PrintStream.java
@@ -287,24 +287,21 @@ public class PrintStream extends FilterOutputStream implements Appendable,
     }
 
     /**
-     * Writes a string formatted by an intermediate {@code Formatter} to the
-     * target stream using the specified format string and arguments. For the
-     * locale, the default value of the current virtual machine instance is
-     * used.
+     * Formats {@code args} according to the format string {@code format}, and writes the result
+     * to this stream. This method uses the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      *
-     * @param format
-     *            the format string used for {@link java.util.Formatter#format}.
+     * @param format the format string (see {@link java.util.Formatter#format})
      * @param args
      *            the list of arguments passed to the formatter. If there are
-     *            more arguments than required by the {@code format} string,
-     *            then the additional arguments are ignored.
+     *            more arguments than required by {@code format},
+     *            additional arguments are ignored.
      * @return this stream.
      * @throws IllegalFormatException
      *             if the format string is illegal or incompatible with the
      *             arguments, if there are not enough arguments or if any other
      *             error regarding the format string or arguments is detected.
-     * @throws NullPointerException
-     *             if {@code format} is {@code null}.
+     * @throws NullPointerException if {@code format == null}
      */
     public PrintStream format(String format, Object... args) {
         return format(Locale.getDefault(), format, args);
diff --git a/luni/src/main/java/java/io/PrintWriter.java b/luni/src/main/java/java/io/PrintWriter.java
index 34842a9..9f5f3cd 100644
--- a/luni/src/main/java/java/io/PrintWriter.java
+++ b/luni/src/main/java/java/io/PrintWriter.java
@@ -281,24 +281,22 @@ public class PrintWriter extends Writer {
     }
 
     /**
-     * Writes a string formatted by an intermediate {@code Formatter} to the
-     * target using the specified format string and arguments. For the locale,
-     * the default value of the current virtual machine instance is used. If
-     * automatic flushing is enabled then the buffer is flushed as well.
+     * Formats {@code args} according to the format string {@code format}, and writes the result
+     * to this stream. This method uses the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * If automatic flushing is enabled then the buffer is flushed as well.
      *
-     * @param format
-     *            the format string used for {@link java.util.Formatter#format}.
+     * @param format the format string (see {@link java.util.Formatter#format})
      * @param args
      *            the list of arguments passed to the formatter. If there are
-     *            more arguments than required by the {@code format} string,
-     *            then the additional arguments are ignored.
+     *            more arguments than required by {@code format},
+     *            additional arguments are ignored.
      * @return this writer.
      * @throws IllegalFormatException
      *             if the format string is illegal or incompatible with the
      *             arguments, if there are not enough arguments or if any other
      *             error regarding the format string or arguments is detected.
-     * @throws NullPointerException
-     *             if {@code format} is {@code null}.
+     * @throws NullPointerException if {@code format == null}
      */
     public PrintWriter format(String format, Object... args) {
         return format(Locale.getDefault(), format, args);
diff --git a/luni/src/main/java/java/lang/String.java b/luni/src/main/java/java/lang/String.java
index 495cc63..c7236d5 100644
--- a/luni/src/main/java/java/lang/String.java
+++ b/luni/src/main/java/java/lang/String.java
@@ -1696,8 +1696,9 @@ public final class String implements Serializable, Comparable<String>, CharSeque
     }
 
     /**
-     * Converts this string to lowercase, using the rules of the default locale.
-     * 
+     * Converts this string to lowercase, using the rules of the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     *
      * @return a new lowercase string, or {@code this} if it's already all-lowercase.
      */
     public String toLowerCase() {
@@ -1732,8 +1733,9 @@ public final class String implements Serializable, Comparable<String>, CharSeque
     }
 
     /**
-     * Converts this this string to uppercase, using the rules of the default locale.
-     * 
+     * Converts this this string to uppercase, using the rules of the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     *
      * @return a new uppercase string, or {@code this} if it's already all-uppercase.
      */
     public String toUpperCase() {
@@ -2167,24 +2169,20 @@ public final class String implements Serializable, Comparable<String>, CharSeque
      * Returns a localized formatted string, using the supplied format and arguments,
      * using the user's default locale.
      * 
-     * <p>Note that this method can be dangerous: the user's default locale may
-     * not be the locale you tested in, and this may have unexpected effects on
-     * the output. In particular, floating point numbers may be output with
-     * ',' instead of '.' as the decimal separator if that's what the user's
-     * locale dictates. If you're formatting a string other than for human
+     * <p>If you're formatting a string other than for human
      * consumption, you should use the {@code format(Locale, String, Object...)}
-     * overload and supply {@code Locale.US}.
+     * overload and supply {@code Locale.US}. See
+     * "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * 
-     * @param format
-     *            a format string.
+     * @param format the format string (see {@link java.util.Formatter#format})
      * @param args
-     *            arguments to replace format specifiers (may be none).
+     *            the list of arguments passed to the formatter. If there are
+     *            more arguments than required by {@code format},
+     *            additional arguments are ignored.
      * @return the formatted string.
-     * @throws NullPointerException
-     *             if {@code format} is {@code null}.
+     * @throws NullPointerException if {@code format == null}
      * @throws java.util.IllegalFormatException
      *             if the format is invalid.
-     * @see java.util.Formatter
      * @since 1.5
      */
     public static String format(String format, Object... args) {
@@ -2194,35 +2192,26 @@ public final class String implements Serializable, Comparable<String>, CharSeque
     /**
      * Returns a formatted string, using the supplied format and arguments,
      * localized to the given locale.
-     * <p>
-     * Note that this is a convenience method. Using it involves creating an
-     * internal {@link java.util.Formatter} instance on-the-fly, which is
-     * somewhat costly in terms of memory and time. This is probably acceptable
-     * if you use the method only rarely, but if you rely on it for formatting a
-     * large number of strings, consider creating and reusing your own
-     * {@link java.util.Formatter} instance instead.
-     *
-     * @param loc
+     * 
+     * @param locale
      *            the locale to apply; {@code null} value means no localization.
-     * @param format
-     *            a format string.
+     * @param format the format string (see {@link java.util.Formatter#format})
      * @param args
-     *            arguments to replace format specifiers (may be none).
+     *            the list of arguments passed to the formatter. If there are
+     *            more arguments than required by {@code format},
+     *            additional arguments are ignored.
      * @return the formatted string.
-     * @throws NullPointerException
-     *             if {@code format} is {@code null}.
+     * @throws NullPointerException if {@code format == null}
      * @throws java.util.IllegalFormatException
      *             if the format is invalid.
-     * @see java.util.Formatter
      * @since 1.5
      */
-    public static String format(Locale loc, String format, Object... args) {
+    public static String format(Locale locale, String format, Object... args) {
         if (format == null) {
             throw new NullPointerException("null format argument");
         }
-        int bufferSize = format.length()
-                + (args == null ? 0 : args.length * 10);
-        Formatter f = new Formatter(new StringBuilder(bufferSize), loc);
+        int bufferSize = format.length() + (args == null ? 0 : args.length * 10);
+        Formatter f = new Formatter(new StringBuilder(bufferSize), locale);
         return f.format(format, args).toString();
     }
 
diff --git a/luni/src/main/java/java/util/Currency.java b/luni/src/main/java/java/util/Currency.java
index 6b6e902..a3ab15c 100644
--- a/luni/src/main/java/java/util/Currency.java
+++ b/luni/src/main/java/java/util/Currency.java
@@ -133,46 +133,32 @@ public final class Currency implements Serializable {
     }
 
     /**
-     * Returns this {@code Currency}'s ISO 4217 currency code.
-     *
-     * @return this {@code Currency}'s ISO 4217 currency code.
+     * Returns this currency's ISO 4217 currency code.
      */
     public String getCurrencyCode() {
         return currencyCode;
     }
 
     /**
-     * Returns the symbol for this currency in the default locale. For instance,
-     * if the default locale is the US, the symbol of the US dollar is "$". For
-     * other locales it may be "US$". If no symbol can be determined, the ISO
-     * 4217 currency code of the US dollar is returned.
-     *
-     * @return the symbol for this {@code Currency} in the default {@code Locale}.
+     * Returns the localized currency symbol for this currency in the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      */
     public String getSymbol() {
         return getSymbol(Locale.getDefault());
     }
 
     /**
-     * Returns the symbol for this currency in the given {@code Locale}.
+     * Returns the localized currency symbol for this currency in {@code locale}.
      * That is, given "USD" and Locale.US, you'd get "$", but given "USD" and a non-US locale,
      * you'd get "US$".
-     * <p>
-     * If the locale only specifies a language rather than a language and a countries (e.g.
-     * {@code Locale.JAPANESE, new Locale("en","")}), the the ISO
-     * 4217 currency code is returned.
-     * <p>
-     * If there is no currency symbol specific to this locale does not exist, the
-     * ISO 4217 currency code is returned.
-     * <p>
      *
-     * @param locale
-     *            the locale for which the currency symbol should be returned.
-     * @return the representation of this {@code Currency}'s symbol in the specified
-     *         locale.
+     * <p>If the locale only specifies a language rather than a language and a country (such as
+     * {@code Locale.JAPANESE} or {new Locale("en", "")} rather than {@code Locale.JAPAN} or
+     * {new Locale("en", "US")}), the ISO 4217 currency code is returned.
+     *
+     * <p>If there is no locale-specific currency symbol, the ISO 4217 currency code is returned.
      */
     public String getSymbol(Locale locale) {
-        // BEGIN android-changed
         if (locale.getCountry().length() == 0) {
             return currencyCode;
         }
@@ -186,7 +172,6 @@ public final class Currency implements Serializable {
         // Try ICU, and fall back to the currency code if ICU has nothing.
         String symbol = Resources.getCurrencySymbolNative(locale.toString(), currencyCode);
         return symbol != null ? symbol : currencyCode;
-        // END android-changed
     }
 
     /**
diff --git a/luni/src/main/java/java/util/Formatter.java b/luni/src/main/java/java/util/Formatter.java
index dec1416..91209d4 100644
--- a/luni/src/main/java/java/util/Formatter.java
+++ b/luni/src/main/java/java/util/Formatter.java
@@ -553,11 +553,11 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a {@code Formatter}.
      *
-     * The output is written to a {@code StringBuilder} which can be acquired by invoking
-     * {@link #out()} and whose content can be obtained by calling
-     * {@code toString()}.
+     * <p>The output is written to a {@code StringBuilder} which can be acquired by invoking
+     * {@link #out()} and whose content can be obtained by calling {@code toString}.
      *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      */
     public Formatter() {
         this(new StringBuilder(), Locale.getDefault());
@@ -567,8 +567,9 @@ public final class Formatter implements Closeable, Flushable {
      * Constructs a {@code Formatter} whose output will be written to the
      * specified {@code Appendable}.
      *
-     * The locale for the {@code Formatter} is the default {@code Locale}.
-     *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param a
      *            the output destination of the {@code Formatter}. If {@code a} is {@code null},
      *            then a {@code StringBuilder} will be used.
@@ -580,9 +581,8 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a {@code Formatter} with the specified {@code Locale}.
      *
-     * The output is written to a {@code StringBuilder} which can be acquired by invoking
-     * {@link #out()} and whose content can be obtained by calling
-     * {@code toString()}.
+     * <p>The output is written to a {@code StringBuilder} which can be acquired by invoking
+     * {@link #out()} and whose content can be obtained by calling {@code toString}.
      *
      * @param l
      *            the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null},
@@ -616,10 +616,11 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a {@code Formatter} whose output is written to the specified file.
      *
-     * The charset of the {@code Formatter} is the default charset.
-     *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
+     * <p>The charset of the {@code Formatter} is the default charset.
      *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param fileName
      *            the filename of the file that is used as the output
      *            destination for the {@code Formatter}. The file will be truncated to
@@ -641,8 +642,9 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a {@code Formatter} whose output is written to the specified file.
      *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
-     *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param fileName
      *            the filename of the file that is used as the output
      *            destination for the {@code Formatter}. The file will be truncated to
@@ -700,8 +702,9 @@ public final class Formatter implements Closeable, Flushable {
      *
      * The charset of the {@code Formatter} is the default charset.
      *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
-     *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param file
      *            the {@code File} that is used as the output destination for the
      *            {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File}
@@ -723,8 +726,9 @@ public final class Formatter implements Closeable, Flushable {
      * Constructs a {@code Formatter} with the given charset,
      * and whose output is written to the specified {@code File}.
      *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
-     *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param file
      *            the {@code File} that is used as the output destination for the
      *            {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File}
@@ -791,10 +795,11 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a {@code Formatter} whose output is written to the specified {@code OutputStream}.
      *
-     * The charset of the {@code Formatter} is the default charset.
-     *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
+     * <p>The charset of the {@code Formatter} is the default charset.
      *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param os
      *            the stream to be used as the destination of the {@code Formatter}.
      */
@@ -807,8 +812,9 @@ public final class Formatter implements Closeable, Flushable {
      * Constructs a {@code Formatter} with the given charset,
      * and whose output is written to the specified {@code OutputStream}.
      *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
-     *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param os
      *            the stream to be used as the destination of the {@code Formatter}.
      * @param csn
@@ -844,10 +850,11 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a {@code Formatter} whose output is written to the specified {@code PrintStream}.
      *
-     * The charset of the {@code Formatter} is the default charset.
-     *
-     * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
+     * <p>The charset of the {@code Formatter} is the default charset.
      *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+     * 
      * @param ps
      *            the {@code PrintStream} used as destination of the {@code Formatter}. If
      *            {@code ps} is {@code null}, then a {@code NullPointerException} will
diff --git a/luni/src/main/java/java/util/Locale.java b/luni/src/main/java/java/util/Locale.java
index 75250b4..9195abc 100644
--- a/luni/src/main/java/java/util/Locale.java
+++ b/luni/src/main/java/java/util/Locale.java
@@ -17,23 +17,16 @@
 
 package java.util;
 
-// BEGIN android-changed
-// import java.io.File;
+import com.ibm.icu4jni.util.Resources;
 import java.io.IOException;
 import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.ObjectStreamField;
 import java.io.Serializable;
 import java.security.AccessController;
-// import java.util.zip.ZipEntry;
-// import java.util.zip.ZipFile;
-
 import org.apache.harmony.luni.util.PriviAction;
 import org.apache.harmony.luni.util.Util;
 
-import com.ibm.icu4jni.util.Resources;
-// END android-changed
-
 /**
  * {@code Locale} represents a language/country/variant combination. Locales are used to
  * alter the presentation of information such as numbers or dates to suit the conventions
@@ -58,9 +51,24 @@ import com.ibm.icu4jni.util.Resources;
  * spoken in Spain), for example. The opposite may well be true for a device sold in Europe.
  * (This limitation even affects those locales pre-defined as constants in this class.)
  *
- * <p>You can use {@code getDefault} to get an appropriate locale for the device you're
- * running on, or {@code getAvailableLocales} to get a list of all the locales available
- * on the device you're running on.
+ * <p>You can use {@code getDefault} to get an appropriate locale for the <i>user</i> of
+ * the device you're running on, or {@code getAvailableLocales} to get a list of all the locales
+ * available on the device you're running on.
+ *
+ * <a name="default_locale"><h3>Be wary of the default locale</h3></a>
+ * <p>Note that there are many convenience methods that automatically use the default locale, but
+ * these may not be as convenient as you imagine. The default locale is appropriate for anything
+ * that involves presenting data to the user. You should use the user's date/time formats, number
+ * formats, rules for conversion to lowercase, and so on. A common mistake is to implicitly use the
+ * default locale when producing output meant to be machine-readable. This tends to work on the
+ * developer's test devices but fail when run on a device whose user is in a less conventional
+ * locale. For example, if you're formatting floating-point numbers some locales will use
+ * {@code ','} as the decimal point. That's correct for human-readable output, but likely to cause
+ * problems if presented to another computer ({@code Double.parseDouble} can't parse such a number,
+ * for example). The best choice for computer-readable output is usually {@code Locale.US}: this
+ * locale is guaranteed to be available on all devices, and the combination of no surprising
+ * behavior and frequent use (especially for computer-computer communication) means that it tends
+ * to be the most efficient choice too.
  *
  * @see ResourceBundle
  */
diff --git a/luni/src/main/java/java/util/TimeZone.java b/luni/src/main/java/java/util/TimeZone.java
index 2b35e61..dd320b8 100644
--- a/luni/src/main/java/java/util/TimeZone.java
+++ b/luni/src/main/java/java/util/TimeZone.java
@@ -214,7 +214,8 @@ public abstract class TimeZone implements Serializable, Cloneable {
      * Gets the LONG name for this {@code TimeZone} for the default {@code Locale} in standard
      * time. If the name is not available, the result is in the format
      * {@code GMT[+-]hh:mm}.
-     *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @return the {@code TimeZone} name.
      */
     public final String getDisplayName() {
@@ -238,7 +239,8 @@ public abstract class TimeZone implements Serializable, Cloneable {
      * Gets the specified style of name ({@code LONG} or {@code SHORT}) for this {@code TimeZone} for
      * the default {@code Locale} in either standard or daylight time as specified. If
      * the name is not available, the result is in the format {@code GMT[+-]hh:mm}.
-     *
+     * <p>The {@code Locale} used is the user's default locale.
+     * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
      * @param daylightTime
      *            {@code true} for daylight time, {@code false} for standard
      *            time.