8326627: Document Double/Float.valueOf(String) behavior for numeric strings with non-ASCII digits

Reviewed-by: iris, jlu

src/java.base/share/classes/java/lang/Double.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -815,10 +815,6 @@ public final class Double extends Number
      * 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 @@ public final class Double extends Number
      *  }
      * }
      *
+     * @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.
      * @return     a {@code Double} object holding the value
      *             represented by the {@code String} argument.

src/java.base/share/classes/java/lang/Float.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -489,10 +489,6 @@ public final class Float extends Number
      * Finally, after rounding a {@code Float} object representing
      * this {@code float} 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;
@@ -516,6 +512,16 @@ public final class Float extends Number
      * for {@link Double#valueOf Double.valueOf} lists a regular
      * expression which can be used to screen the input.
      *
+     * @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).floatValue();
+     * }
+     * where {@code l} is the desired locale, or
+     * {@link java.util.Locale#ROOT} if locale insensitive.
+     *
      * @param   s   the string to be parsed.
      * @return  a {@code Float} object holding the value
      *          represented by the {@code String} argument.

test/jdk/java/lang/Double/ParseDouble.java

@@ -193,6 +193,7 @@ public class ParseDouble {
         "\u0661e\u0661", // 1e1 in Arabic-Indic digits
         "\u06F1e\u06F1", // 1e1 in Extended Arabic-Indic digits
         "\u0967e\u0967", // 1e1 in Devanagari digits
+        "\uD835\uDFD9e\uD835\uDFD9", // 1e1 in Mathematical Alphanumeric Symbols
 
         // JCK test lex03592m3
         ".",

test/jdk/java/lang/Float/ParseFloat.java

@@ -201,7 +201,8 @@ public class ParseFloat {
         // Non-ASCII digits are not recognized
         "\u0661e\u0661", // 1e1 in Arabic-Indic digits
         "\u06F1e\u06F1", // 1e1 in Extended Arabic-Indic digits
-        "\u0967e\u0967" // 1e1 in Devanagari digits
+        "\u0967e\u0967", // 1e1 in Devanagari digits
+        "\uD835\uDFD9e\uD835\uDFD9" // 1e1 in Mathematical Alphanumeric Symbols
     };
 
     static String goodStrings[] = {