Summary

In java.text.NumberFormat (and concrete subclasses), clarify that the integer and fraction limits do not impact parsing.

Problem

Some users have had a misconception that the integer and fraction limits impact parsing behavior. These limits are set by the setter methods, but can also be set by a String pattern (for DecimalFormat). For example, a user thought that a pattern such as "#" which contains no fraction digits, should only parse integral values.

Solution

Clarify in the specification that these limits only impact formatting behavior. This change occurs in all of the NumberFormat [get|set][Maximum|Minimum][Integer|Fraction]Digits methods and is inherited by implementing classes. This update is done as a normative change.

1. The long standing behavior of the JDK reference implementation is that these limits only impacting formatting behavior.
2. It is not common that you would want to suppress the range of digits of accepted during parsing. NumberFormat already provides setParseIntegerOnly() which can be used to toggle integral only parsing.

To better standardize the wording of the classes, inheritDoc tags were used, which required some minor word re-shuffling. As a result, the parameter wording in the relevant NumberFormat setter methods - "A concrete subclass may enforce an upper limit to this value appropriate to the numeric type being formatted." was moved under an implNote which is 1) more appropriate and 2) is not inherited by the subclasses.

Specification

Under the NumberFormat Customizing NumberFormat section,

  * <li> {@link #setMinimumFractionDigits(int)}; Use to adjust the expected digits when
  * formatting. Use any of the other minimum/maximum or fraction/integer setter methods
- * in the same manner.
+ * in the same manner. These methods have no impact on parsing behavior.

Under the DecimalFormat Integer and Fraction Digit Limits section,

  * <h3 id="digit_limits"> Integer and Fraction Digit Limits </h3>
+ * The integer and fraction digit limits are set by either applying a {@link ##patterns
+ * pattern}, or using one of the appropriate {@code DecimalFormat} setter methods,
+ * for example, {@link #setMinimumFractionDigits(int)}. These limits have no impact on
+ * parsing behavior.

In the NumberFormat getters. (Other 3 related getters omitted for brevity, they follow the exact same format barring the respective max/min and integer/fraction differences.)

     /**
      * Returns the maximum number of digits allowed in the integer portion of a
-     * number.
+     * number during formatting.
      *
      * @return the maximum number of digits
      * @see #setMaximumIntegerDigits

In the NumberFormat setters. (Other 3 related setters omitted for brevity, they follow the exact same format barring the respective max/min and integer/fraction differences.)

     /**
      * Sets the maximum number of digits allowed in the integer portion of a
-     * number. maximumIntegerDigits must be ≥ minimumIntegerDigits.  If the
-     * new value for maximumIntegerDigits is less than the current value
-     * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
-     * the new value.
+     * number during formatting. {@code maximumIntegerDigits} must be ≥
+     * {@code minimumIntegerDigits}. If the new value for {@code
+     * maximumIntegerDigits} is less than the current value of
+     * {@code minimumIntegerDigits}, then {@code minimumIntegerDigits} will
+     * also be set to the new value.
+     *
+     * @implNote
+     * A concrete subclass may enforce an upper limit to this value appropriate
+     * to the numeric type being formatted.
      *
      * @param newValue the maximum number of integer digits to be shown; if
-     * less than zero, then zero is used. The concrete subclass may enforce an
-     * upper limit to this value appropriate to the numeric type being formatted.
+     * less than zero, then zero is used.
      * @see #getMaximumIntegerDigits
      */

DecimalFormat and CompactNumberFormat are also updated to utilize the inheritDoc tag to inherit the new wording in the relevant methods. For example, in CompactNumberFormat.setMaximumIntegerDigits(int newValue). (The rest of the getter and setter changes for DecimalFormat and CompactNumberFormat are also omitted for brevity; they follow the same style of change.)

     /**
-     * Sets the maximum number of digits allowed in the integer portion of a
-     * number.
-     * The maximum allowed integer range is 309, if the {@code newValue} > 309,
-     * then the maximum integer digits count is set to 309. Negative input
-     * values are replaced with 0.
-     *
-     * @param newValue the maximum number of integer digits to be shown
-     * @see #getMaximumIntegerDigits()
+     * {@inheritDoc}
+     * <p>The maximum allowed integer range is 309, if the {@code newValue} &gt;
+     * 309, then the maximum integer digits count is set to 309.
      */
     @Override
     public void setMaximumIntegerDigits(int newValue) {

Lastly, amend some wording, (done as a unrelated drive by fix) specific to DecimalFormat.getMaximumIntegerDigits() which improves the call out to the distinct behavior of maximumIntegerDigits,

     /**
-     * Gets the maximum number of digits allowed in the integer portion of a
-     * number. The maximum number of integer digits can be set by either {@link #setMaximumIntegerDigits(int)}
-     * or {@link #applyPattern(String)}. See the {@link ##patterns Pattern Section} for
-     * comprehensive rules regarding maximum integer digits in patterns.
+     * {@inheritDoc}
+     * <p>Unlike the other digit limits, {@code maximumIntegerDigits} is not
+     * updated by {@code DecimalFormats} created or updated with a string pattern.
      * @see #setMaximumIntegerDigits
+     * @see ##patterns Pattern Section
      * @see ##digit_limits Integer and Fraction Digit Limits
      */