Intl docstrings + fix of some Intl bindings (#7995)

* Intl docstrings

* Fix examples

* Some reverts

* Changelog

* Fix tests

* Remove bigint plural rules select functions (not supported by most runtimes)

* Changelog

Author: fhammerschmidt

CHANGELOG.md

@@ -14,6 +14,8 @@
 
 #### :boom: Breaking Change
 
+- Fix some Intl bindings (`Intl.Collator.supportedLocalesOf`, `Intl.DateTimeFormat.supportedLocalesOf`, `Intl.ListFormat.supportedLocalesOf`, `Intl.NumberFormat.supportedLocalesOf`, `Intl.PluralRules.supportedLocalesOf`, `Intl.RelativeTimeFormat.supportedLocalesOf`, `Intl.Segmenter.supportedLocalesOf`) which return `array<string>` and not their corresponding main type `t`. Also remove `Intl.PluralRules.selectBigInt` and `Intl.PluralRules.selectRangeBigInt` which don't work in many JS runtimes. https://github.com/rescript-lang/rescript/pull/7995
+
 #### :eyeglasses: Spec Compliance
 
 #### :rocket: New Feature

packages/@rescript/runtime/Stdlib_Intl.res

@@ -10,16 +10,46 @@ module Segmenter = Stdlib_Intl_Segmenter
 module Segments = Stdlib_Intl_Segments
 
 /**
-@throws RangeError
+`getCanonicalLocalesExn(locale)` returns the canonical form of `locale`.
+
+Throws `RangeError` when the locale string is malformed.
+
+See [`Intl.getCanonicalLocales`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales) on MDN.
+
+## Examples
+
+```rescript
+Intl.getCanonicalLocalesExn("EN-US") == ["en-US"]
+```
 */
 external getCanonicalLocalesExn: string => array<string> = "Intl.getCanonicalLocales"
 
 /**
-@throws RangeError
+`getCanonicalLocalesManyExn(locales)` canonicalises every locale in `locales`.
+
+Throws `RangeError` when any locale string is malformed.
+
+See [`Intl.getCanonicalLocales`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales) on MDN.
+
+## Examples
+
+```rescript
+Intl.getCanonicalLocalesManyExn(["EN-US", "fr"]) == ["en-US", "fr"]
+```
 */
 external getCanonicalLocalesManyExn: array<string> => array<string> = "Intl.getCanonicalLocales"
 
 /**
-@throws RangeError
+`supportedValuesOfExn(key)` returns the list of values supported by the runtime for the feature identified by `key`.
+
+Throws `RangeError` when `key` is unsupported.
+
+See [`Intl.supportedValuesOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf) on MDN.
+
+## Examples
+
+```rescript
+Intl.supportedValuesOfExn("calendar")->Array.includes("gregory") == true
+```
 */
 external supportedValuesOfExn: string => array<string> = "Intl.supportedValuesOf"

packages/@rescript/runtime/Stdlib_Intl_Collator.res

@@ -26,14 +26,60 @@ type resolvedOptions = {
 
 type supportedLocalesOptions = {localeMatcher: Stdlib_Intl_Common.localeMatcher}
 
+/**
+Creates a new `Intl.Collator` instance that can compare strings using locale-aware rules.
+
+See [`Intl.Collator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator) on MDN.
+
+## Examples
+
+```rescript
+let collator = Intl.Collator.make(~locales=["en"])
+collator->Intl.Collator.compare("apple", "banana") < 0
+```
+*/
 @new external make: (~locales: array<string>=?, ~options: options=?) => t = "Intl.Collator"
 
+/**
+`supportedLocalesOf(locales, ~options)` filters `locales` to those supported by the runtime for collation.
+
+See [`Intl.Collator.supportedLocalesOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/supportedLocalesOf) on MDN.
+
+## Examples
+
+```rescript
+Intl.Collator.supportedLocalesOf(["en-US", "klingon"]) == ["en-US"]
+
+```
+*/
 @val
-external supportedLocalesOf: (array<string>, ~options: supportedLocalesOptions=?) => t =
+external supportedLocalesOf: (array<string>, ~options: supportedLocalesOptions=?) => array<string> =
   "Intl.Collator.supportedLocalesOf"
 
+/**
+`resolvedOptions(collator)` returns the locale and collation settings in use.
+
+See [`Intl.Collator.prototype.resolvedOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/resolvedOptions) on MDN.
+
+## Examples
+
+```rescript
+let collator = Intl.Collator.make(~locales=["en-US"])
+Intl.Collator.resolvedOptions(collator).locale == "en-US"
+```
+*/
 @send external resolvedOptions: t => resolvedOptions = "resolvedOptions"
 
+/**
+`compare(collator, a, b)` compares two strings using the rules of `collator`. Returns a negative number when `a` comes before `b`, `0` when equal, and a positive number otherwise.
+
+## Examples
+
+```rescript
+let collator = Intl.Collator.make(~locales=["en-US"])
+collator->Intl.Collator.compare("apple", "banana") < 0
+```
+*/
 @send external compare: (t, string, string) => int = "compare"
 
 /**

packages/@rescript/runtime/Stdlib_Intl_DateTimeFormat.res

@@ -1,3 +1,7 @@
+/***
+Bindings to JavaScript's `Intl.DateTimeFormat`.
+*/
+
 @notUndefined
 type t
 
@@ -106,22 +110,110 @@ type dateTimeRangePart = {
   source: dateTimeRangeSource,
 }
 
+/**
+Creates a new `Intl.DateTimeFormat` instance for formatting date values.
+
+See [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.DateTimeFormat.make(~locales=["en-US"], ~options={timeStyle: #short})
+let sampleDate = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
+formatter->Intl.DateTimeFormat.format(sampleDate)->String.length > 0
+```
+*/
 @new external make: (~locales: array<string>=?, ~options: options=?) => t = "Intl.DateTimeFormat"
 
+/**
+`supportedLocalesOf(locales, ~options)` filters `locales` to those supported by the runtime for date/time formatting.
+
+See [`Intl.DateTimeFormat.supportedLocalesOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/supportedLocalesOf) on MDN.
+
+## Examples
+
+```rescript
+Intl.DateTimeFormat.supportedLocalesOf(["en-US", "klingon"]) == ["en-US"]
+```
+*/
 @val
-external supportedLocalesOf: (array<string>, ~options: supportedLocalesOptions=?) => t =
+external supportedLocalesOf: (array<string>, ~options: supportedLocalesOptions=?) => array<string> =
   "Intl.DateTimeFormat.supportedLocalesOf"
 
+/**
+`resolvedOptions(formatter)` returns the actual locale and formatting options in use.
+
+See [`Intl.DateTimeFormat.prototype.resolvedOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.DateTimeFormat.make(~locales=["en-US"])
+Intl.DateTimeFormat.resolvedOptions(formatter).locale == "en-US"
+```
+*/
 @send external resolvedOptions: t => resolvedOptions = "resolvedOptions"
 
+/**
+`format(formatter, date)` returns the formatted string for `date`.
+
+## Examples
+
+```rescript
+let formatter = Intl.DateTimeFormat.make(~locales=["en"])
+let date = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
+formatter->Intl.DateTimeFormat.format(date)->String.length > 0
+```
+*/
 @send external format: (t, Stdlib_Date.t) => string = "format"
-@send
-external formatToParts: (t, Stdlib_Date.t) => array<dateTimePart> = "formatToParts"
 
+/**
+`formatToParts(formatter, date)` breaks the formatted output into an array of parts.
+
+See [`Intl.DateTimeFormat.prototype.formatToParts`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatToParts) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.DateTimeFormat.make(~locales=["en"])
+let date = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
+formatter->Intl.DateTimeFormat.formatToParts(date)->Array.length > 0
+```
+*/
+@send external formatToParts: (t, Stdlib_Date.t) => array<dateTimePart> = "formatToParts"
+
+/**
+`formatRange(formatter, ~startDate, ~endDate)` formats the range between `startDate` and `endDate`.
+
+See [`Intl.DateTimeFormat.prototype.formatRange`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatRange) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.DateTimeFormat.make(~locales=["en-US"], ~options={dateStyle: #short})
+let startDate = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
+let endDate = Js.Date.makeWithYMD(~year=2024, ~month=1, ~date=1)
+formatter->Intl.DateTimeFormat.formatRange(~startDate=startDate, ~endDate=endDate)->String.length > 0
+```
+*/
 @send
 external formatRange: (t, ~startDate: Stdlib_Date.t, ~endDate: Stdlib_Date.t) => string =
   "formatRange"
 
+/**
+`formatRangeToParts(formatter, ~startDate, ~endDate)` returns an array describing how the range would be rendered.
+
+See [`Intl.DateTimeFormat.prototype.formatRangeToParts`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatRangeToParts) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.DateTimeFormat.make(~locales=["en-US"], ~options={dateStyle: #short})
+let startDate = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
+let endDate = Js.Date.makeWithYMD(~year=2024, ~month=1, ~date=1)
+formatter->Intl.DateTimeFormat.formatRangeToParts(~startDate=startDate, ~endDate=endDate)->Array.length > 0
+```
+*/
 @send
 external formatRangeToParts: (
   t,

packages/@rescript/runtime/Stdlib_Intl_ListFormat.res

@@ -36,15 +36,73 @@ type resolvedOptions = {
 
 type supportedLocalesOptions = {localeMatcher: Stdlib_Intl_Common.localeMatcher}
 
+/**
+Creates a new `Intl.ListFormat` instance for formatting lists.
+
+See [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.ListFormat.make(~locales=["en"], ~options={\"type": #conjunction})
+formatter->Intl.ListFormat.format(["apples", "bananas", "cherries"]) == "apples, bananas, and cherries"
+```
+*/
 @new external make: (~locales: array<string>=?, ~options: options=?) => t = "Intl.ListFormat"
 
+/**
+`supportedLocalesOf(locales, ~options)` filters `locales` to those supported for list formatting.
+
+See [`Intl.ListFormat.supportedLocalesOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/supportedLocalesOf) on MDN.
+
+## Examples
+
+```rescript
+Intl.ListFormat.supportedLocalesOf(["en-US", "klingon"]) == ["en-US"]
+```
+*/
 @val
-external supportedLocalesOf: (array<string>, ~options: supportedLocalesOptions=?) => t =
+external supportedLocalesOf: (array<string>, ~options: supportedLocalesOptions=?) => array<string> =
   "Intl.ListFormat.supportedLocalesOf"
 
+/**
+`resolvedOptions(formatter)` returns the actual options being used.
+
+See [`Intl.ListFormat.prototype.resolvedOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/resolvedOptions) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.ListFormat.make(~locales=["en"])
+Intl.ListFormat.resolvedOptions(formatter).locale == "en"
+```
+*/
 @send external resolvedOptions: t => resolvedOptions = "resolvedOptions"
 
+/**
+`format(formatter, items)` returns the formatted list string.
+
+## Examples
+
+```rescript
+let formatter = Intl.ListFormat.make(~locales=["en"])
+formatter->Intl.ListFormat.format(["a", "b"]) == "a and b"
+```
+*/
 @send external format: (t, array<string>) => string = "format"
+
+/**
+`formatToParts(formatter, items)` returns the list as an array of parts describing how it would be rendered.
+
+See [`Intl.ListFormat.prototype.formatToParts`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/formatToParts) on MDN.
+
+## Examples
+
+```rescript
+let formatter = Intl.ListFormat.make(~locales=["en"])
+formatter->Intl.ListFormat.formatToParts(["a", "b"])->Array.length > 0
+```
+*/
 @send external formatToParts: (t, array<string>) => array<listPart> = "formatToParts"
 
 /**