Summary

It is not apparent in the method descriptions of NumberFormat.setGroupingUsed(boolean)/isGroupingUsed() that both formatting and parsing are affected.

Problem

The relevant methods do not mention that both formatting and parsing are affected when grouping is used. This has been the actual long-standing behavior of the NumberFormat implementation (DecimalFormat) provided by the OpenJDK reference implementation. The bug reporter assumed grouping would not affect parsing, and was also surprised by the results when it did.

Solution

The relevant methods should mention that grouping affects both parsing and formatting. Note that JDK-8329222 made this apparent in the class description, but the relevant methods should be updated directly as well. Parsing examples are also provided in addition to the existing formatting example under isGroupingUsed(). The wording is changed to remove the ambiguous "might" wording.

Specification

Update NumberFormat.isGroupingUsed()

     /**
-     * Returns true if grouping is used in this format. For example, in the
-     * English locale, with grouping on, the number 1234567 might be formatted
-     * as "1,234,567". The grouping separator as well as the size of each group
-     * is locale dependent and is determined by sub-classes of NumberFormat.
+     * Returns true if grouping is used in this format. This applies to both
+     * formatting and parsing. The grouping separator as well as the size of each
+     * group is locale dependent and is determined by sub-classes of NumberFormat.
+     * For example, consider a {@code NumberFormat} that expects a "{@code ,}"
+     * grouping separator symbol with a grouping size of 3.
+     * <ul>
+     *   <li> Formatting {@code 1234567} with grouping on returns {@code "1,234,567"}
+     *   <li> Parsing {@code "1,234,567"} with grouping off returns {@code 1}
+     *   <li> Parsing {@code "1,234,567"} with grouping off when {@link #isStrict()}
+     *        returns {@code true} throws {@code ParseException}
+     * </ul>
      *
      * @return {@code true} if grouping is used;
      *         {@code false} otherwise
      * @see #setGroupingUsed
+     * @see ##leniency Leniency Section
      */

Update NumberFormat.setGroupingUsed(boolean)

     /**
      * Set whether or not grouping will be used in this format.
+     * This applies to both formatting and parsing.
      *
      * @param newValue {@code true} if grouping is used;
      *                 {@code false} otherwise