8358804: Improve the API Note of BigDecimal.valueOf(double)

Reviewed-by: bpb, darcy, iris

Author: rgiulietti

src/java.base/share/classes/java/math/BigDecimal.java

@@ -1372,10 +1372,15 @@ static BigDecimal zeroValueOf(int scale) {
      * by the {@link Double#toString(double)} method.
      *
      * @apiNote This is generally the preferred way to convert a
-     * {@code double} (or {@code float}) into a {@code BigDecimal}, as
+     * {@code double} into a {@code BigDecimal}, as
      * the value returned is equal to that resulting from constructing
      * a {@code BigDecimal} from the result of using {@link
      * Double#toString(double)}.
+     * <p>
+     * While a {@code float} argument {@code v} can be passed to this method,
+     * the result often contains many more trailing digits than the precision
+     * of a {@code float}.
+     * Consider using {@code new BigDecimal(Float.toString(v))} instead.
      *
      * @param  val {@code double} to convert to a {@code BigDecimal}.
      * @return a {@code BigDecimal} whose value is equal to or approximately