Summary

Clarify the logic of maximum and minimum integer/fraction digit limits in the specification of DecimalFormat.

Problem

The specification for these methods is unclear and has caused confusion. For example, DecimalFormat::getMaximumIntegerDigits states, "Gets the maximum number of digits allowed in the integer portion of a number. For formatting numbers other than BigInteger and BigDecimal objects, the lower of the return value and 309 is used".

This has caused users to think that return value will always be at most 309. This assumption is incorrect, in reality, whatever the DecimalFormat object was initialized with, or the value set by the corresponding setter is returned.

Solution

Remove the 309/340 wording from the general method descriptions of the getters and setters. Instead, replace it with a section in the class description, that the methods can point to. In the new description, it is apparent that the 309/340 values are not values potentially returned, but rather internally used by DecimalFormat. An implSpec tag is used here, since there may exist other external subclasses that define their own digit limits.

Additionally, getMaximumIntegerDigits() is updated to make apparent the non-obvious rules for max integer digits.

Specification

Add the following section to the class description,

+ * <h3 id="digit_limits"> Integer and Fraction Digit Limits </h3>
+ *
+ * @implSpec
+ * When formatting a {@code Number} other than {@code BigInteger} and
+ * {@code BigDecimal}, {@code 309} is used as the upper limit for integer digits,
+ * and {@code 340} as the upper limit for fraction digits. This occurs, even if
+ * one of the {@code DecimalFormat} getter methods, for example, {@link #getMinimumFractionDigits()}
+ * returns a numerically greater value.
+ *

Update the eight setters/getters with the following format, (add an @see tag and drop the additional description)

     /**
      * Sets the minimum number of digits allowed in the fraction portion of a
-     * number.
-     * For formatting numbers other than {@code BigInteger} and
-     * {@code BigDecimal} objects, the lower of {@code newValue} and
-     * 340 is used. Negative input values are replaced with 0.
+     * number. Negative input values are replaced with 0.
      * @see NumberFormat#setMinimumFractionDigits
+     * @see ##digit_limits Integer and Fraction Digit Limits
      */
     @Override
     public void setMinimumFractionDigits(int newValue) {

getMaximumIntegerDigits(),

     /**
      * Gets the maximum number of digits allowed in the integer portion of a
-     * number.
-     * For formatting numbers other than {@code BigInteger} and
-     * {@code BigDecimal} objects, the lower of the return value and
-     * 309 is used.
+     * 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.
      * @see #setMaximumIntegerDigits
+     * @see ##digit_limits Integer and Fraction Digit Limits
      */
     @Override
     public int getMaximumIntegerDigits() {