Improve the explanation in `Intl.NumberFormat()` about `maximumSignificantDigits` property

[Rafael-Martins]

Proposal

I think that we can add some clarification on how maximumSignificantDigits works, and also the relation with roundingPriority.

Task list

• [ ] Reformulate docs for maximumSignificantDigits
• [ ] Reformulate docs for roundingPriority
• [ ] Reformulate docs for maximumFractionDigits

Additional information

I will add more insight's about it soon as I can.

Are you willing to support this work?

Yes

Depends on

No response

[Rumyra]

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat

[Josh-Cena]

@Rafael-Martins It is unclear what you want to see happening. Could you describe more about your intended change?

[Josh-Cena]

From the linked issues, I think I have a better idea where the confusion comes from. The problem is that new Intl.NumberFormat('en-US').format(3e-18) returns '0', but new Intl.NumberFormat('en-US', { maximumSignificantDigits: 21 }).format(3e-18) returns 0.000000000000000003, even when we claim that maximumSignificantDigits: 21 is the default value.

The problem is that "FractionDigits" and "SignificantDigits" are not unconditionally applied with the default values. You can observe this with resolvedOptions:

new Intl.NumberFormat('en-US').resolvedOptions();
// {
//     "locale": "en-US",
//     "numberingSystem": "latn",
//     "style": "decimal",
//     "minimumIntegerDigits": 1,
//     "minimumFractionDigits": 0,
//     "maximumFractionDigits": 3,
//     "useGrouping": "auto",
//     "notation": "standard",
//     "signDisplay": "auto",
//     "roundingIncrement": 1,
//     "roundingMode": "halfExpand",
//     "roundingPriority": "auto",
//     "trailingZeroDisplay": "auto"
// }

new Intl.NumberFormat('en-US', { maximumSignificantDigits: 21 }).resolvedOptions();
// {
//     "locale": "en-US",
//     "numberingSystem": "latn",
//     "style": "decimal",
//     "minimumIntegerDigits": 1,
//     "minimumSignificantDigits": 1,
//     "maximumSignificantDigits": 21,
//     "useGrouping": "auto",
//     "notation": "standard",
//     "signDisplay": "auto",
//     "roundingIncrement": 1,
//     "roundingMode": "halfExpand",
//     "roundingPriority": "auto",
//     "trailingZeroDisplay": "auto"
// }

The "defaults" mentioned are only applied if at least one option from the group (*SignificantDigits/*FractionDigits) is specified. This means that the resolved options will always contain both or neither of maximumSignificantDigits and minimumSignificantDigits (ditto for *FractionDigits). However, we never mentioned what happens if none of the max/min options are specified.

We should be very explicit about when and how the SD/FD options are set in the resolved options:

Which options are set?	In which case?
All four options	roundingPriority is not auto
Only the two SD options	roundingPriority is auto and an SD option is explicitly set
None of the four options	roundingPriority is auto, notation is compact, and none of the four options are specified
Only the two FD options	Otherwise

We need to fix both the constructor page and the resolvedOptions page to clarify these interactions.

[Rafael-Martins]

Oh, that is exactly the problem, I can work on the clarifications in a near future, if you want!

[Josh-Cena]

I will be working on this, as I already had plans for improving these Intl docs. Thanks for confirming though!