Summary

Document the behavior of valueOf(String) methods in java.lang.Double and java.lang.Float classes for numeric strings with non-ASCII digits.

Problem

Users incorrectly expect that those methods would accept non-ASCII digits, partly because the equivalent method in java.lang.Integer class accepts them.

Solution

Clarify the behavior as an @apiNote, with an example that uses java.text.NumberFormat. There already is the wording for "localized" string representations that encourages users to use NumberFormat, but it is different from this non-ASCII digit issue. Combining it with this new description in a single @apiNote would be helpful.

Specification

Modify valueOf(String) methods in java.lang.Double and java.lang.Float classes as follows (Double as an example. Float version replaces doubleValue() with floatValue()):

@@ -815,10 +815,6 @@
      * Finally, after rounding a {@code Double} object representing
      * this {@code double} value is returned.
      *
-     * <p> To interpret localized string representations of a
-     * floating-point value, use subclasses of {@link
-     * java.text.NumberFormat}.
-     *
      * <p>Note that trailing format specifiers, specifiers that
      * determine the type of a floating-point literal
      * ({@code 1.0f} is a {@code float} value;
@@ -889,6 +885,16 @@
      *  }
      * }
      *
+     * @apiNote To interpret localized string representations of a
+     * floating-point value, or string representations that have
+     * non-ASCII digits, use {@link java.text.NumberFormat}. For
+     * example,
+     * {@snippet lang="java" :
+     *     NumberFormat.getInstance(l).parse(s).doubleValue();
+     * }
+     * where {@code l} is the desired locale, or
+     * {@link java.util.Locale#ROOT} if locale insensitive.
+     *
      * @param      s   the string to be parsed.