7092447: Clarify the default locale used in each locale sensitive operation

Reviewed-by: okutsu

src/share/classes/java/text/DateFormat.java

@@ -439,7 +439,12 @@ public abstract class DateFormat extends Format {
 
     /**
      * Gets the time formatter with the default formatting style
-     * for the default locale.
+     * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getTimeInstance(int, Locale) getTimeInstance(DEFAULT,
+     *     Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @return a time formatter.
      */
     public final static DateFormat getTimeInstance()
@@ -449,7 +454,12 @@ public abstract class DateFormat extends Format {
 
     /**
      * Gets the time formatter with the given formatting style
-     * for the default locale.
+     * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getTimeInstance(int, Locale) getTimeInstance(style,
+     *     Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @param style the given formatting style. For example,
      * SHORT for "h:mm a" in the US locale.
      * @return a time formatter.
@@ -475,7 +485,12 @@ public abstract class DateFormat extends Format {
 
     /**
      * Gets the date formatter with the default formatting style
-     * for the default locale.
+     * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getDateInstance(int, Locale) getDateInstance(DEFAULT,
+     *     Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @return a date formatter.
      */
     public final static DateFormat getDateInstance()
@@ -485,7 +500,12 @@ public abstract class DateFormat extends Format {
 
     /**
      * Gets the date formatter with the given formatting style
-     * for the default locale.
+     * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getDateInstance(int, Locale) getDateInstance(style,
+     *     Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @param style the given formatting style. For example,
      * SHORT for "M/d/yy" in the US locale.
      * @return a date formatter.
@@ -511,7 +531,12 @@ public abstract class DateFormat extends Format {
 
     /**
      * Gets the date/time formatter with the default formatting style
-     * for the default locale.
+     * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getDateTimeInstance(int, int, Locale) getDateTimeInstance(DEFAULT,
+     *     DEFAULT, Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @return a date/time formatter.
      */
     public final static DateFormat getDateTimeInstance()
@@ -521,7 +546,12 @@ public abstract class DateFormat extends Format {
 
     /**
      * Gets the date/time formatter with the given date and time
-     * formatting styles for the default locale.
+     * formatting styles for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getDateTimeInstance(int, int, Locale) getDateTimeInstance(dateStyle,
+     *     timeStyle, Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @param dateStyle the given date formatting style. For example,
      * SHORT for "M/d/yy" in the US locale.
      * @param timeStyle the given time formatting style. For example,

src/share/classes/java/text/DateFormatSymbols.java

@@ -104,14 +104,19 @@ public class DateFormatSymbols implements Serializable, Cloneable {
 
     /**
      * Construct a DateFormatSymbols object by loading format data from
-     * resources for the default locale. This constructor can only
+     * resources for the default {@link java.util.Locale.Category#FORMAT FORMAT}
+     * locale. This constructor can only
      * construct instances for the locales supported by the Java
      * runtime environment, not for those supported by installed
      * {@link java.text.spi.DateFormatSymbolsProvider DateFormatSymbolsProvider}
      * implementations. For full locale coverage, use the
      * {@link #getInstance(Locale) getInstance} method.
-     *
+     * <p>This is equivalent to calling
+     * {@link #DateFormatSymbols(Locale)
+     *     DateFormatSymbols(Locale.getDefault(Locale.Category.FORMAT))}.
      * @see #getInstance()
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @exception  java.util.MissingResourceException
      *             if the resources for the default locale cannot be
      *             found or cannot be loaded.
@@ -302,6 +307,10 @@ public class DateFormatSymbols implements Serializable, Cloneable {
      * as for those supported by installed
      * {@link java.text.spi.DateFormatSymbolsProvider DateFormatSymbolsProvider}
      * implementations.
+     * <p>This is equivalent to calling {@link #getInstance(Locale)
+     *     getInstance(Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @return a <code>DateFormatSymbols</code> instance.
      * @since 1.6
      */

src/share/classes/java/text/DecimalFormat.java

@@ -381,7 +381,8 @@ public class DecimalFormat extends NumberFormat {
 
     /**
      * Creates a DecimalFormat using the default pattern and symbols
-     * for the default locale. This is a convenient way to obtain a
+     * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * This is a convenient way to obtain a
      * DecimalFormat when internationalization is not the main concern.
      * <p>
      * To obtain standard formats for a given locale, use the factory methods
@@ -411,7 +412,8 @@ public class DecimalFormat extends NumberFormat {
 
     /**
      * Creates a DecimalFormat using the given pattern and the symbols
-     * for the default locale. This is a convenient way to obtain a
+     * for the default {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * This is a convenient way to obtain a
      * DecimalFormat when internationalization is not the main concern.
      * <p>
      * To obtain standard formats for a given locale, use the factory methods

src/share/classes/java/text/DecimalFormatSymbols.java

@@ -71,13 +71,19 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter;
 public class DecimalFormatSymbols implements Cloneable, Serializable {
 
     /**
-     * Create a DecimalFormatSymbols object for the default locale.
+     * Create a DecimalFormatSymbols object for the default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
      * This constructor can only construct instances for the locales
      * supported by the Java runtime environment, not for those
      * supported by installed
      * {@link java.text.spi.DecimalFormatSymbolsProvider DecimalFormatSymbolsProvider}
      * implementations. For full locale coverage, use the
      * {@link #getInstance(Locale) getInstance} method.
+     * <p>This is equivalent to calling
+     * {@link #DecimalFormatSymbols(Locale)
+     *     DecimalFormatSymbols(Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      */
     public DecimalFormatSymbols() {
         initialize( Locale.getDefault(Locale.Category.FORMAT) );
@@ -133,6 +139,11 @@ public class DecimalFormatSymbols implements Cloneable, Serializable {
      * as for those supported by installed
      * {@link java.text.spi.DecimalFormatSymbolsProvider
      * DecimalFormatSymbolsProvider} implementations.
+     * <p>This is equivalent to calling
+     * {@link #getInstance(Locale)
+     *     getInstance(Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @return a <code>DecimalFormatSymbols</code> instance.
      * @since 1.6
      */

src/share/classes/java/text/MessageFormat.java

@@ -348,7 +348,8 @@ public class MessageFormat extends Format {
     private static final long serialVersionUID = 6479157306784022952L;
 
     /**
-     * Constructs a MessageFormat for the default locale and the
+     * Constructs a MessageFormat for the default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale and the
      * specified pattern.
      * The constructor first sets the locale, then parses the pattern and
      * creates a list of subformats for the format elements contained in it.

src/share/classes/java/text/NumberFormat.java

@@ -389,7 +389,8 @@ public abstract class NumberFormat extends Format  {
     //============== Locale Stuff =====================
 
     /**
-     * Returns a general-purpose number format for the current default locale.
+     * Returns a general-purpose number format for the current default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
      * This is the same as calling
      * {@link #getNumberInstance() getNumberInstance()}.
      */
@@ -407,7 +408,13 @@ public abstract class NumberFormat extends Format  {
     }
 
     /**
-     * Returns a general-purpose number format for the current default locale.
+     * Returns a general-purpose number format for the current default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getNumberInstance(Locale)
+     *     getNumberInstance(Locale.getDefault(Locale.Category.FORMAT))}.
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      */
     public final static NumberFormat getNumberInstance() {
         return getInstance(Locale.getDefault(Locale.Category.FORMAT), NUMBERSTYLE);
@@ -421,14 +428,20 @@ public abstract class NumberFormat extends Format  {
     }
 
     /**
-     * Returns an integer number format for the current default locale. The
+     * Returns an integer number format for the current default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale. The
      * returned number format is configured to round floating point numbers
      * to the nearest integer using half-even rounding (see {@link
      * java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}) for formatting,
      * and to parse only the integer part of an input string (see {@link
      * #isParseIntegerOnly isParseIntegerOnly}).
+     * <p>This is equivalent to calling
+     * {@link #getIntegerInstance(Locale)
+     *     getIntegerInstance(Locale.getDefault(Locale.Category.FORMAT))}.
      *
      * @see #getRoundingMode()
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @return a number format for integer values
      * @since 1.4
      */
@@ -453,7 +466,14 @@ public abstract class NumberFormat extends Format  {
     }
 
     /**
-     * Returns a currency format for the current default locale.
+     * Returns a currency format for the current default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getCurrencyInstance(Locale)
+     *     getCurrencyInstance(Locale.getDefault(Locale.Category.FORMAT))}.
+     *
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      */
     public final static NumberFormat getCurrencyInstance() {
         return getInstance(Locale.getDefault(Locale.Category.FORMAT), CURRENCYSTYLE);
@@ -467,7 +487,14 @@ public abstract class NumberFormat extends Format  {
     }
 
     /**
-     * Returns a percentage format for the current default locale.
+     * Returns a percentage format for the current default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
+     * <p>This is equivalent to calling
+     * {@link #getPercentInstance(Locale)
+     *     getPercentInstance(Locale.getDefault(Locale.Category.FORMAT))}.
+     *
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      */
     public final static NumberFormat getPercentInstance() {
         return getInstance(Locale.getDefault(Locale.Category.FORMAT), PERCENTSTYLE);

src/share/classes/java/text/SimpleDateFormat.java

@@ -547,7 +547,8 @@ public class SimpleDateFormat extends DateFormat {
 
     /**
      * Constructs a <code>SimpleDateFormat</code> using the default pattern and
-     * date format symbols for the default locale.
+     * date format symbols for the default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
      * <b>Note:</b> This constructor may not support all locales.
      * For full coverage, use the factory methods in the {@link DateFormat}
      * class.
@@ -560,11 +561,17 @@ public class SimpleDateFormat extends DateFormat {
 
     /**
      * Constructs a <code>SimpleDateFormat</code> using the given pattern and
-     * the default date format symbols for the default locale.
+     * the default date format symbols for the default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
      * <b>Note:</b> This constructor may not support all locales.
      * For full coverage, use the factory methods in the {@link DateFormat}
      * class.
+     * <p>This is equivalent to calling
+     * {@link #SimpleDateFormat(String, Locale)
+     *     SimpleDateFormat(pattern, Locale.getDefault(Locale.Category.FORMAT))}.
      *
+     * @see java.util.Locale#getDefault(java.util.Locale.Category)
+     * @see java.util.Locale.Category#FORMAT
      * @param pattern the pattern describing the date and time format
      * @exception NullPointerException if the given pattern is null
      * @exception IllegalArgumentException if the given pattern is invalid

src/share/classes/java/time/format/DateTimeFormatSymbols.java

@@ -121,10 +121,16 @@ public final class DateTimeFormatSymbols {
     }
 
     /**
-     * Obtains symbols for the default locale.
+     * Obtains symbols for the default
+     * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
      * <p>
      * This method provides access to locale sensitive symbols.
+     * <p>
+     * This is equivalent to calling
+     * {@link #of(Locale)
+     *     of(Locale.getDefault(Locale.Category.FORMAT))}.
      *
+     * @see java.util.Locale.Category#FORMAT
      * @return the info, not null
      */
     public static DateTimeFormatSymbols ofDefaultLocale() {

src/share/classes/java/util/Calendar.java

@@ -1572,7 +1572,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
 
     /**
      * Constructs a Calendar with the default time zone
-     * and locale.
+     * and the default {@link java.util.Locale.Category#FORMAT FORMAT}
+     * locale.
      * @see     TimeZone#getDefault
      */
     protected Calendar()
@@ -1600,7 +1601,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
     /**
      * Gets a calendar using the default time zone and locale. The
      * <code>Calendar</code> returned is based on the current time
-     * in the default time zone with the default locale.
+     * in the default time zone with the default
+     * {@link Locale.Category#FORMAT FORMAT} locale.
      *
      * @return a Calendar.
      */
@@ -1614,7 +1616,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
     /**
      * Gets a calendar using the specified time zone and default locale.
      * The <code>Calendar</code> returned is based on the current time
-     * in the given time zone with the default locale.
+     * in the given time zone with the default
+     * {@link Locale.Category#FORMAT FORMAT} locale.
      *
      * @param zone the time zone to use
      * @return a Calendar.

src/share/classes/java/util/Currency.java

@@ -472,12 +472,18 @@ public final class Currency implements Serializable {
     }
 
     /**
-     * Gets the symbol of this currency for the default locale.
+     * Gets the symbol of this currency for the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale.
      * For example, for the US Dollar, the symbol is "$" if the default
      * locale is the US, while for other locales it may be "US$". If no
      * symbol can be determined, the ISO 4217 currency code is returned.
+     * <p>
+     * This is equivalent to calling
+     * {@link #getSymbol(Locale)
+     *     getSymbol(Locale.getDefault(Locale.Category.DISPLAY))}.
      *
-     * @return the symbol of this currency for the default locale
+     * @return the symbol of this currency for the default
+     *     {@link Locale.Category#DISPLAY DISPLAY} locale
      */
     public String getSymbol() {
         return getSymbol(Locale.getDefault(Locale.Category.DISPLAY));
@@ -533,10 +539,16 @@ public final class Currency implements Serializable {
 
     /**
      * Gets the name that is suitable for displaying this currency for
-     * the default locale.  If there is no suitable display name found
+     * the default {@link Locale.Category#DISPLAY DISPLAY} locale.
+     * If there is no suitable display name found
      * for the default locale, the ISO 4217 currency code is returned.
+     * <p>
+     * This is equivalent to calling
+     * {@link #getDisplayName(Locale)
+     *     getDisplayName(Locale.getDefault(Locale.Category.DISPLAY))}.
      *
-     * @return the display name of this currency for the default locale
+     * @return the display name of this currency for the default
+     *     {@link Locale.Category#DISPLAY DISPLAY} locale
      * @since 1.7
      */
     public String getDisplayName() {

src/share/classes/java/util/Formatter.java

@@ -1900,7 +1900,8 @@ public final class Formatter implements Closeable, Flushable {
      * which may be retrieved by invoking {@link #out out()} and whose
      * current content may be converted into a string by invoking {@link
      * #toString toString()}.  The locale used is the {@linkplain
-     * Locale#getDefault() default locale} for this instance of the Java
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
      * virtual machine.
      */
     public Formatter() {
@@ -1910,8 +1911,10 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a new formatter with the specified destination.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault() default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * @param  a
      *         Destination for the formatted output.  If {@code a} is
@@ -1961,8 +1964,10 @@ public final class Formatter implements Closeable, Flushable {
      * java.nio.charset.Charset#defaultCharset() default charset} for this
      * instance of the Java virtual machine.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault() default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * @param  fileName
      *         The name of the file to use as the destination of this
@@ -1989,8 +1994,10 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a new formatter with the specified file name and charset.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * @param  fileName
      *         The name of the file to use as the destination of this
@@ -2068,8 +2075,10 @@ public final class Formatter implements Closeable, Flushable {
      * java.nio.charset.Charset#defaultCharset() default charset} for this
      * instance of the Java virtual machine.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault() default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * @param  file
      *         The file to use as the destination of this formatter.  If the
@@ -2096,8 +2105,10 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a new formatter with the specified file and charset.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * @param  file
      *         The file to use as the destination of this formatter.  If the
@@ -2171,8 +2182,10 @@ public final class Formatter implements Closeable, Flushable {
     /**
      * Constructs a new formatter with the specified print stream.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault() default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * <p> Characters are written to the given {@link java.io.PrintStream
      * PrintStream} object and are therefore encoded using that object's
@@ -2193,8 +2206,10 @@ public final class Formatter implements Closeable, Flushable {
      * java.nio.charset.Charset#defaultCharset() default charset} for this
      * instance of the Java virtual machine.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault() default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * @param  os
      *         The output stream to use as the destination of this formatter.
@@ -2209,8 +2224,10 @@ public final class Formatter implements Closeable, Flushable {
      * Constructs a new formatter with the specified output stream and
      * charset.
      *
-     * <p> The locale used is the {@linkplain Locale#getDefault default
-     * locale} for this instance of the Java virtual machine.
+     * <p> The locale used is the {@linkplain
+     * Locale#getDefault(Locale.Category) default locale} for
+     * {@linkplain Locale.Category#FORMAT formatting} for this instance of the Java
+     * virtual machine.
      *
      * @param  os
      *         The output stream to use as the destination of this formatter.

src/share/classes/java/util/GregorianCalendar.java

@@ -587,7 +587,8 @@ public class GregorianCalendar extends Calendar {
 
     /**
      * Constructs a default <code>GregorianCalendar</code> using the current time
-     * in the default time zone with the default locale.
+     * in the default time zone with the default
+     * {@link Locale.Category#FORMAT FORMAT} locale.
      */
     public GregorianCalendar() {
         this(TimeZone.getDefaultRef(), Locale.getDefault(Locale.Category.FORMAT));
@@ -596,7 +597,8 @@ public class GregorianCalendar extends Calendar {
 
     /**
      * Constructs a <code>GregorianCalendar</code> based on the current time
-     * in the given time zone with the default locale.
+     * in the given time zone with the default
+     * {@link Locale.Category#FORMAT FORMAT} locale.
      *
      * @param zone the given time zone.
      */

src/share/classes/java/util/Locale.java

@@ -351,7 +351,8 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter;
  * you can use <code>getDisplayLanguage</code> to get the name of
  * the language suitable for displaying to the user. Interestingly,
  * the <code>getDisplayXXX</code> methods are themselves locale-sensitive
- * and have two versions: one that uses the default locale and one
+ * and have two versions: one that uses the default
+ * {@link Locale.Category#DISPLAY DISPLAY} locale and one
  * that uses the locale specified as an argument.
  *
  * <p>The Java Platform provides a number of classes that perform locale-sensitive
@@ -369,7 +370,8 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter;
  * </pre>
  * </blockquote>
  * Each of these methods has two variants; one with an explicit locale
- * and one without; the latter uses the default locale:
+ * and one without; the latter uses the default
+ * {@link Locale.Category#FORMAT FORMAT} locale:
  * <blockquote>
  * <pre>
  *     NumberFormat.getInstance(myLocale)
@@ -1645,11 +1647,15 @@ public final class Locale implements Cloneable, Serializable {
     /**
      * Returns a name for the locale's language that is appropriate for display to the
      * user.
-     * If possible, the name returned will be localized for the default locale.
-     * For example, if the locale is fr_FR and the default locale
+     * If possible, the name returned will be localized for the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale.
+     * For example, if the locale is fr_FR and the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale
      * is en_US, getDisplayLanguage() will return "French"; if the locale is en_US and
-     * the default locale is fr_FR, getDisplayLanguage() will return "anglais".
-     * If the name returned cannot be localized for the default locale,
+     * the default {@link Locale.Category#DISPLAY DISPLAY} locale is fr_FR,
+     * getDisplayLanguage() will return "anglais".
+     * If the name returned cannot be localized for the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale,
      * (say, we don't have a Japanese name for Croatian),
      * this function falls back on the English name, and uses the ISO code as a last-resort
      * value.  If the locale doesn't specify a language, this function returns the empty string.
@@ -1679,10 +1685,12 @@ public final class Locale implements Cloneable, Serializable {
 
     /**
      * Returns a name for the the locale's script that is appropriate for display to
-     * the user. If possible, the name will be localized for the default locale.  Returns
+     * the user. If possible, the name will be localized for the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale.  Returns
      * the empty string if this locale doesn't specify a script code.
      *
-     * @return the display name of the script code for the current default locale
+     * @return the display name of the script code for the current default
+     *     {@link Locale.Category#DISPLAY DISPLAY} locale
      * @since 1.7
      */
     public String getDisplayScript() {
@@ -1695,7 +1703,8 @@ public final class Locale implements Cloneable, Serializable {
      * localized for the given locale. Returns the empty string if
      * this locale doesn't specify a script code.
      *
-     * @return the display name of the script code for the current default locale
+     * @return the display name of the script code for the current default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale
      * @throws NullPointerException if <code>inLocale</code> is <code>null</code>
      * @since 1.7
      */
@@ -1706,11 +1715,15 @@ public final class Locale implements Cloneable, Serializable {
     /**
      * Returns a name for the locale's country that is appropriate for display to the
      * user.
-     * If possible, the name returned will be localized for the default locale.
-     * For example, if the locale is fr_FR and the default locale
+     * If possible, the name returned will be localized for the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale.
+     * For example, if the locale is fr_FR and the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale
      * is en_US, getDisplayCountry() will return "France"; if the locale is en_US and
-     * the default locale is fr_FR, getDisplayCountry() will return "Etats-Unis".
-     * If the name returned cannot be localized for the default locale,
+     * the default {@link Locale.Category#DISPLAY DISPLAY} locale is fr_FR,
+     * getDisplayCountry() will return "Etats-Unis".
+     * If the name returned cannot be localized for the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale,
      * (say, we don't have a Japanese name for Croatia),
      * this function falls back on the English name, and uses the ISO code as a last-resort
      * value.  If the locale doesn't specify a country, this function returns the empty string.
@@ -1762,7 +1775,8 @@ public final class Locale implements Cloneable, Serializable {
 
     /**
      * Returns a name for the locale's variant code that is appropriate for display to the
-     * user.  If possible, the name will be localized for the default locale.  If the locale
+     * user.  If possible, the name will be localized for the default
+     * {@link Locale.Category#DISPLAY DISPLAY} locale.  If the locale
      * doesn't specify a variant code, this function returns the empty string.
      */
     public final String getDisplayVariant() {

src/share/classes/java/util/Scanner.java

@@ -151,7 +151,8 @@ import sun.misc.LRUCache;
  * <p> An instance of this class is capable of scanning numbers in the standard
  * formats as well as in the formats of the scanner's locale. A scanner's
  * <a name="initial-locale">initial locale </a>is the value returned by the {@link
- * java.util.Locale#getDefault} method; it may be changed via the {@link
+ * java.util.Locale#getDefault(Locale.Category)
+ * Locale.getDefault(Locale.Category.FORMAT)} method; it may be changed via the {@link
  * #useLocale} method. The {@link #reset} method will reset the value of the
  * scanner's locale to the initial locale regardless of whether it was
  * previously changed.
@@ -2641,7 +2642,7 @@ public final class Scanner implements Iterator<String>, Closeable {
      *
      * <blockquote><pre>
      *   scanner.useDelimiter("\\p{javaWhitespace}+")
-     *          .useLocale(Locale.getDefault())
+     *          .useLocale(Locale.getDefault(Locale.Category.FORMAT))
      *          .useRadix(10);
      * </pre></blockquote>
      *