effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/DateTime.js

@@ -12,40 +12,87 @@ const TimeZoneTypeId = Internal.TimeZoneTypeId;
 /**
  * Checks whether a value is a `DateTime`.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a `DateTime`.
+ *
+ * @see {@link isUtc} for narrowing a known `DateTime` to UTC
+ * @see {@link isZoned} for narrowing a known `DateTime` to zoned
+ *
  * @category guards
  * @since 3.6.0
  */
 export const isDateTime = Internal.isDateTime;
 /**
- * Checks if a value is a `TimeZone`.
+ * Checks whether a value is a `TimeZone`.
+ *
+ * **When to use**
+ *
+ * Use to narrow unknown input to any `TimeZone` before passing it to APIs that
+ * accept either fixed-offset or named time zones.
+ *
+ * @see {@link isTimeZoneOffset} for narrowing to fixed-offset time zones
+ * @see {@link isTimeZoneNamed} for narrowing to named time zones
  *
  * @category guards
  * @since 3.6.0
  */
 export const isTimeZone = Internal.isTimeZone;
 /**
- * Checks if a value is an offset-based `TimeZone`.
+ * Checks whether a value is an offset-based `TimeZone`.
+ *
+ * **When to use**
+ *
+ * Use when narrowing an unknown or union `TimeZone` value to the fixed-offset
+ * variant before reading its offset in milliseconds.
+ *
+ * @see {@link isTimeZone} for checking either time zone variant
+ * @see {@link isTimeZoneNamed} for narrowing to named time zones
  *
  * @category guards
  * @since 3.6.0
  */
 export const isTimeZoneOffset = Internal.isTimeZoneOffset;
 /**
- * Checks if a value is a named `TimeZone` (IANA time zone).
+ * Checks whether a value is a named `TimeZone` (IANA time zone).
+ *
+ * **When to use**
+ *
+ * Use to narrow an unknown value to the `TimeZone.Named` variant before
+ * reading named-zone fields such as `id`.
+ *
+ * @see {@link isTimeZone} for checking either time zone variant
+ * @see {@link isTimeZoneOffset} for narrowing to fixed-offset time zones
  *
  * @category guards
  * @since 3.6.0
  */
 export const isTimeZoneNamed = Internal.isTimeZoneNamed;
 /**
- * Checks if a `DateTime` is a UTC `DateTime` (no time zone information).
+ * Checks whether a `DateTime` is a UTC `DateTime` (no time zone information).
+ *
+ * **When to use**
+ *
+ * Use to narrow a `DateTime` before passing it to code that requires a UTC
+ * value without an associated time zone.
+ *
+ * @see {@link isZoned} for narrowing to zoned date-times
+ * @see {@link match} for handling both UTC and zoned cases
  *
  * @category guards
  * @since 3.6.0
  */
 export const isUtc = Internal.isUtc;
 /**
- * Checks if a `DateTime` is a zoned `DateTime` (has time zone information).
+ * Checks whether a `DateTime` is a zoned `DateTime` (has time zone information).
+ *
+ * **When to use**
+ *
+ * Use to narrow a known `DateTime` before reading its zone or passing it to
+ * APIs that require `DateTime.Zoned`.
+ *
+ * @see {@link isUtc} for narrowing to UTC date-times
+ * @see {@link match} for handling both UTC and zoned cases
  *
  * @category guards
  * @since 3.6.0
@@ -55,7 +102,7 @@ export const isZoned = Internal.isZoned;
 // instances
 // =============================================================================
 /**
- * An `Equivalence` for comparing two `DateTime` values for equality.
+ * Provides an `Equivalence` for comparing two `DateTime` values for equality.
  *
  * **Details**
  *
@@ -80,7 +127,7 @@ export const isZoned = Internal.isZoned;
  */
 export const Equivalence = Internal.Equivalence;
 /**
- * An `Order` for comparing and sorting `DateTime` values.
+ * Provides an `Order` for comparing and sorting `DateTime` values.
  *
  * **Details**
  *
@@ -107,7 +154,7 @@ export const Equivalence = Internal.Equivalence;
  */
 export const Order = Internal.Order;
 /**
- * Clamp a `DateTime` between a minimum and maximum value.
+ * Returns a `DateTime` constrained between a minimum and maximum value.
  *
  * **Details**
  *
@@ -128,7 +175,7 @@ export const Order = Internal.Order;
  * // clamped equals max (2024-12-31)
  * ```
  *
- * @category instances
+ * @category ordering
  * @since 3.6.0
  */
 export const clamp = Internal.clamp;
@@ -223,7 +270,7 @@ export const makeUnsafe = Internal.makeUnsafe;
  */
 export const makeZonedUnsafe = Internal.makeZonedUnsafe;
 /**
- * Creates a `DateTime.Zoned` from an input and a time zone.
+ * Creates a `DateTime.Zoned` safely from an input and a time zone.
  *
  * **Details**
  *
@@ -263,7 +310,7 @@ export const makeZonedUnsafe = Internal.makeZonedUnsafe;
  */
 export const makeZoned = Internal.makeZoned;
 /**
- * Creates a `DateTime` from supported input values.
+ * Creates a `DateTime` safely from supported input values.
  *
  * **Details**
  *
@@ -303,7 +350,7 @@ export const makeZoned = Internal.makeZoned;
  */
 export const make = Internal.make;
 /**
- * Parses an ISO zoned date-time string into a `DateTime.Zoned`.
+ * Parses an ISO zoned date-time string into a `DateTime.Zoned` safely.
  *
  * **Details**
  *
@@ -334,7 +381,7 @@ export const make = Internal.make;
  */
 export const makeZonedFromString = Internal.makeZonedFromString;
 /**
- * Get the current time using the `Clock` service and convert it to a `DateTime`.
+ * Gets the current time using the `Clock` service and convert it to a `DateTime`.
  *
  * **Example** (Getting the current DateTime)
  *
@@ -370,7 +417,7 @@ export const now = Internal.now;
  */
 export const nowAsDate = Internal.nowAsDate;
 /**
- * Get the current time using `Date.now`.
+ * Gets the current time using `Date.now`.
  *
  * **Details**
  *
@@ -394,7 +441,16 @@ export const nowUnsafe = Internal.nowUnsafe;
 // time zones
 // =============================================================================
 /**
- * For a `DateTime` returns a new `DateTime.Utc`.
+ * Converts a `DateTime` to a UTC `DateTime`.
+ *
+ * **When to use**
+ *
+ * Use to represent the same instant in UTC instead of its current time zone.
+ *
+ * **Details**
+ *
+ * The returned value keeps the same epoch milliseconds and changes only the
+ * `DateTime` representation to UTC.
  *
  * **Example** (Converting DateTime values to UTC)
  *
@@ -414,7 +470,7 @@ export const nowUnsafe = Internal.nowUnsafe;
  */
 export const toUtc = Internal.toUtc;
 /**
- * Set the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
+ * Sets the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
  *
  * **Example** (Setting time zones)
  *
@@ -435,7 +491,7 @@ export const toUtc = Internal.toUtc;
  */
 export const setZone = Internal.setZone;
 /**
- * Add a fixed offset time zone to a `DateTime`.
+ * Adds a fixed offset time zone to a `DateTime`.
  *
  * **Details**
  *
@@ -459,7 +515,7 @@ export const setZone = Internal.setZone;
  */
 export const setZoneOffset = Internal.setZoneOffset;
 /**
- * Attempt to create a named time zone from a IANA time zone identifier.
+ * Attempts to create a named time zone from an IANA time zone identifier.
  *
  * **Details**
  *
@@ -510,7 +566,7 @@ export const zoneMakeNamedUnsafe = Internal.zoneMakeNamedUnsafe;
  */
 export const zoneMakeOffset = Internal.zoneMakeOffset;
 /**
- * Create a named time zone from a IANA time zone identifier.
+ * Creates a named time zone safely from an IANA time zone identifier.
  *
  * **Details**
  *
@@ -533,7 +589,7 @@ export const zoneMakeOffset = Internal.zoneMakeOffset;
  */
 export const zoneMakeNamed = Internal.zoneMakeNamed;
 /**
- * Create a named time zone from a IANA time zone identifier.
+ * Creates a named time zone effectfully from an IANA time zone identifier.
  *
  * **Details**
  *
@@ -577,7 +633,7 @@ export const zoneMakeNamedEffect = Internal.zoneMakeNamedEffect;
  */
 export const zoneMakeLocal = Internal.zoneMakeLocal;
 /**
- * Try to parse a `TimeZone` from a string.
+ * Tries to parse a `TimeZone` from a string safely.
  *
  * **Details**
  *
@@ -602,7 +658,7 @@ export const zoneMakeLocal = Internal.zoneMakeLocal;
  */
 export const zoneFromString = Internal.zoneFromString;
 /**
- * Format a `TimeZone` as a string.
+ * Formats a `TimeZone` as a string.
  *
  * **Example** (Formatting time zones)
  *
@@ -621,7 +677,7 @@ export const zoneFromString = Internal.zoneFromString;
  */
 export const zoneToString = Internal.zoneToString;
 /**
- * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
+ * Sets the time zone of a `DateTime` safely from an IANA time zone identifier. If the
  * time zone is invalid, `None` will be returned.
  *
  * **Example** (Setting named time zones safely)
@@ -641,7 +697,7 @@ export const zoneToString = Internal.zoneToString;
  */
 export const setZoneNamed = Internal.setZoneNamed;
 /**
- * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
+ * Sets the time zone of a `DateTime` from an IANA time zone identifier. If the
  * time zone is invalid, an `IllegalArgumentError` will be thrown.
  *
  * **Example** (Setting named time zones unsafely)
@@ -664,7 +720,7 @@ export const setZoneNamedUnsafe = Internal.setZoneNamedUnsafe;
 // comparisons
 // =============================================================================
 /**
- * Calulate the difference between two `DateTime` values, returning a
+ * Computes the difference between two `DateTime` values, returning a
  * `Duration` representing the amount of time between them.
  *
  * **Details**
@@ -730,7 +786,7 @@ export const min = Internal.min;
  */
 export const max = Internal.max;
 /**
- * Checks if the first `DateTime` is after the second `DateTime`.
+ * Checks whether the first `DateTime` is after the second `DateTime`.
  *
  * **Example** (Checking whether a DateTime is later)
  *
@@ -749,7 +805,7 @@ export const max = Internal.max;
  */
 export const isGreaterThan = Internal.isGreaterThan;
 /**
- * Checks if the first `DateTime` is after or equal to the second `DateTime`.
+ * Checks whether the first `DateTime` is after or equal to the second `DateTime`.
  *
  * **Example** (Checking whether a DateTime is later or equal)
  *
@@ -770,7 +826,7 @@ export const isGreaterThan = Internal.isGreaterThan;
  */
 export const isGreaterThanOrEqualTo = Internal.isGreaterThanOrEqualTo;
 /**
- * Checks if the first `DateTime` is before the second `DateTime`.
+ * Checks whether the first `DateTime` is before the second `DateTime`.
  *
  * **Example** (Checking whether a DateTime is earlier)
  *
@@ -789,7 +845,7 @@ export const isGreaterThanOrEqualTo = Internal.isGreaterThanOrEqualTo;
  */
 export const isLessThan = Internal.isLessThan;
 /**
- * Checks if the first `DateTime` is before or equal to the second `DateTime`.
+ * Checks whether the first `DateTime` is before or equal to the second `DateTime`.
  *
  * **Example** (Checking whether a DateTime is earlier or equal)
  *
@@ -810,7 +866,7 @@ export const isLessThan = Internal.isLessThan;
  */
 export const isLessThanOrEqualTo = Internal.isLessThanOrEqualTo;
 /**
- * Checks if a `DateTime` is between two other `DateTime` values (inclusive).
+ * Checks whether a `DateTime` is between two other `DateTime` values (inclusive).
  *
  * **Example** (Checking whether a DateTime is within bounds)
  *
@@ -829,7 +885,7 @@ export const isLessThanOrEqualTo = Internal.isLessThanOrEqualTo;
  */
 export const between = Internal.between;
 /**
- * Checks if a `DateTime` is in the future compared to the current time.
+ * Checks effectfully if a `DateTime` is in the future compared to the current time.
  *
  * **Details**
  *
@@ -852,7 +908,7 @@ export const between = Internal.between;
  */
 export const isFuture = Internal.isFuture;
 /**
- * Checks if a `DateTime` is in the future compared to the current time.
+ * Checks synchronously if a `DateTime` is in the future compared to the current time.
  *
  * **Details**
  *
@@ -875,7 +931,7 @@ export const isFuture = Internal.isFuture;
  */
 export const isFutureUnsafe = Internal.isFutureUnsafe;
 /**
- * Checks if a `DateTime` is in the past compared to the current time.
+ * Checks effectfully if a `DateTime` is in the past compared to the current time.
  *
  * **Details**
  *
@@ -898,7 +954,7 @@ export const isFutureUnsafe = Internal.isFutureUnsafe;
  */
 export const isPast = Internal.isPast;
 /**
- * Checks if a `DateTime` is in the past compared to the current time.
+ * Checks synchronously if a `DateTime` is in the past compared to the current time.
  *
  * **Details**
  *
@@ -924,7 +980,7 @@ export const isPastUnsafe = Internal.isPastUnsafe;
 // conversions
 // =============================================================================
 /**
- * Get the UTC `Date` of a `DateTime`.
+ * Gets the UTC `Date` of a `DateTime`.
  *
  * **Details**
  *
@@ -948,7 +1004,7 @@ export const isPastUnsafe = Internal.isPastUnsafe;
  */
 export const toDateUtc = Internal.toDateUtc;
 /**
- * Convert a `DateTime` to a `Date`, applying the time zone first.
+ * Converts a `DateTime` to a `Date`, applying the time zone first.
  *
  * **Details**
  *
@@ -974,7 +1030,7 @@ export const toDateUtc = Internal.toDateUtc;
  */
 export const toDate = Internal.toDate;
 /**
- * Calculate the time zone offset of a `DateTime.Zoned` in milliseconds.
+ * Computes the time zone offset of a `DateTime.Zoned` in milliseconds.
  *
  * **Details**
  *
@@ -999,7 +1055,7 @@ export const toDate = Internal.toDate;
  */
 export const zonedOffset = Internal.zonedOffset;
 /**
- * Format the time zone offset of a `DateTime.Zoned` as an ISO string.
+ * Formats the time zone offset of a `DateTime.Zoned` as an ISO string.
  *
  * **Details**
  *
@@ -1023,7 +1079,7 @@ export const zonedOffset = Internal.zonedOffset;
  */
 export const zonedOffsetIso = Internal.zonedOffsetIso;
 /**
- * Get the milliseconds since the Unix epoch of a `DateTime`.
+ * Gets the milliseconds since the Unix epoch of a `DateTime`.
  *
  * **Details**
  *
@@ -1045,7 +1101,7 @@ export const zonedOffsetIso = Internal.zonedOffsetIso;
  */
 export const toEpochMillis = Internal.toEpochMillis;
 /**
- * Remove the time aspect of a `DateTime`, first adjusting for the time
+ * Removes the time aspect of a `DateTime`, first adjusting for the time
  * zone. It will return a `DateTime.Utc` only containing the date.
  *
  * **Example** (Removing time components)
@@ -1071,7 +1127,7 @@ export const removeTime = Internal.removeTime;
 // parts
 // =============================================================================
 /**
- * Get the different parts of a `DateTime` as an object.
+ * Gets the time-zone-adjusted parts of a `DateTime` as an object.
  *
  * **Details**
  *
@@ -1103,7 +1159,7 @@ export const removeTime = Internal.removeTime;
  */
 export const toParts = Internal.toParts;
 /**
- * Get the different parts of a `DateTime` as an object.
+ * Gets the UTC parts of a `DateTime` as an object.
  *
  * **Details**
  *
@@ -1128,7 +1184,7 @@ export const toParts = Internal.toParts;
  */
 export const toPartsUtc = Internal.toPartsUtc;
 /**
- * Get a part of a `DateTime` as a number.
+ * Gets one UTC part of a `DateTime` as a number.
  *
  * **Details**
  *
@@ -1149,7 +1205,7 @@ export const toPartsUtc = Internal.toPartsUtc;
  */
 export const getPartUtc = Internal.getPartUtc;
 /**
- * Get a part of a `DateTime` as a number.
+ * Gets one time-zone-adjusted part of a `DateTime` as a number.
  *
  * **Details**
  *
@@ -1172,7 +1228,7 @@ export const getPartUtc = Internal.getPartUtc;
  */
 export const getPart = Internal.getPart;
 /**
- * Set the different parts of a `DateTime` as an object.
+ * Sets time-zone-adjusted parts on a `DateTime`.
  *
  * **Details**
  *
@@ -1198,7 +1254,7 @@ export const getPart = Internal.getPart;
  */
 export const setParts = Internal.setParts;
 /**
- * Set the different parts of a `DateTime` as an object.
+ * Sets UTC parts on a `DateTime`.
  *
  * **Details**
  *
@@ -1256,7 +1312,7 @@ export const setPartsUtc = Internal.setPartsUtc;
  */
 export class CurrentTimeZone extends /*#__PURE__*/Context.Service()("effect/DateTime/CurrentTimeZone") {}
 /**
- * Set the time zone of a `DateTime` to the current time zone, which is
+ * Sets the time zone of a `DateTime` to the current time zone, which is
  * determined by the `CurrentTimeZone` service.
  *
  * **Example** (Setting the current time zone)
@@ -1277,7 +1333,7 @@ export class CurrentTimeZone extends /*#__PURE__*/Context.Service()("effect/Date
  */
 export const setZoneCurrent = self => Effect.map(CurrentTimeZone, zone => setZone(self, zone));
 /**
- * Provide the `CurrentTimeZone` to an effect.
+ * Provides the `CurrentTimeZone` to an effect.
  *
  * **Example** (Providing the current time zone)
  *
@@ -1296,7 +1352,7 @@ export const setZoneCurrent = self => Effect.map(CurrentTimeZone, zone => setZon
  */
 export const withCurrentZone = /*#__PURE__*/provideService(CurrentTimeZone);
 /**
- * Provide the `CurrentTimeZone` to an effect, using the system's local time
+ * Provides the `CurrentTimeZone` to an effect, using the system's local time
  * zone.
  *
  * **Example** (Providing the local time zone)
@@ -1315,7 +1371,7 @@ export const withCurrentZone = /*#__PURE__*/provideService(CurrentTimeZone);
  */
 export const withCurrentZoneLocal = effect => Effect.provideServiceEffect(effect, CurrentTimeZone, Effect.sync(zoneMakeLocal));
 /**
- * Provide the `CurrentTimeZone` to an effect, using a offset.
+ * Provides the `CurrentTimeZone` to an effect, using an offset.
  *
  * **Example** (Providing a fixed-offset time zone)
  *
@@ -1333,7 +1389,7 @@ export const withCurrentZoneLocal = effect => Effect.provideServiceEffect(effect
  */
 export const withCurrentZoneOffset = /*#__PURE__*/dual(2, (effect, offset) => Effect.provideService(effect, CurrentTimeZone, zoneMakeOffset(offset)));
 /**
- * Provide the `CurrentTimeZone` to an effect using an IANA time zone
+ * Provides the `CurrentTimeZone` to an effect using an IANA time zone
  * identifier.
  *
  * **Details**
@@ -1356,7 +1412,7 @@ export const withCurrentZoneOffset = /*#__PURE__*/dual(2, (effect, offset) => Ef
  */
 export const withCurrentZoneNamed = /*#__PURE__*/dual(2, (effect, zone) => Effect.provideServiceEffect(effect, CurrentTimeZone, zoneMakeNamedEffect(zone)));
 /**
- * Get the current time as a `DateTime.Zoned`, using the `CurrentTimeZone`.
+ * Gets the current time as a `DateTime.Zoned`, using the `CurrentTimeZone`.
  *
  * **Example** (Getting the current time in the current zone)
  *
@@ -1377,7 +1433,12 @@ export const nowInCurrentZone = /*#__PURE__*/Effect.flatMap(now, setZoneCurrent)
 // mapping
 // =============================================================================
 /**
- * Modify a `DateTime` by applying a function to a cloned `Date` instance.
+ * Modifies a `DateTime` with a mutable local `Date` copy.
+ *
+ * **When to use**
+ *
+ * Use to adjust calendar fields in the `DateTime`'s own time zone with an
+ * existing `Date` mutation API.
  *
  * **Details**
  *
@@ -1406,7 +1467,12 @@ export const nowInCurrentZone = /*#__PURE__*/Effect.flatMap(now, setZoneCurrent)
  */
 export const mutate = Internal.mutate;
 /**
- * Modify a `DateTime` by applying a function to a cloned UTC `Date` instance.
+ * Modifies a `DateTime` with a mutable UTC `Date` copy.
+ *
+ * **When to use**
+ *
+ * Use to adjust the instant with an existing `Date` mutation API that works on
+ * UTC calendar fields.
  *
  * **Example** (Mutating DateTime values with UTC Dates)
  *
@@ -1429,7 +1495,7 @@ export const mutate = Internal.mutate;
  */
 export const mutateUtc = Internal.mutateUtc;
 /**
- * Transform a `DateTime` by applying a function to the number of milliseconds
+ * Transforms a `DateTime` by applying a function to the number of milliseconds
  * since the Unix epoch.
  *
  * **Example** (Mapping epoch milliseconds)
@@ -1531,7 +1597,23 @@ export const match = Internal.match;
 // math
 // =============================================================================
 /**
- * Add the given `Duration` to a `DateTime`.
+ * Adds the given `Duration` to a `DateTime`.
+ *
+ * **When to use**
+ *
+ * Use to move a `DateTime` by an elapsed duration such as minutes, seconds, or
+ * milliseconds.
+ *
+ * **Details**
+ *
+ * The duration is converted to milliseconds and added to the epoch
+ * milliseconds. Zoned values keep their original time zone.
+ *
+ * **Gotchas**
+ *
+ * This is elapsed-time arithmetic, not calendar-aware local date arithmetic.
+ * Use `add` when adding days, weeks, months, or years should account for the
+ * date/time zone rules.
  *
  * **Example** (Adding durations)
  *
@@ -1544,12 +1626,15 @@ export const match = Internal.match;
  * )
  * ```
  *
+ * @see {@link add} for calendar-aware date/time part arithmetic
+ * @see {@link subtractDuration} for subtracting an elapsed duration
+ *
  * @category math
  * @since 3.6.0
  */
 export const addDuration = Internal.addDuration;
 /**
- * Subtract the given `Duration` from a `DateTime`.
+ * Subtracts the given `Duration` from a `DateTime`.
  *
  * **Example** (Subtracting durations)
  *
@@ -1567,7 +1652,7 @@ export const addDuration = Internal.addDuration;
  */
 export const subtractDuration = Internal.subtractDuration;
 /**
- * Add the given `amount` of `unit`'s to a `DateTime`.
+ * Adds the given `amount` of `unit` to a `DateTime`.
  *
  * **Details**
  *
@@ -1590,7 +1675,7 @@ export const subtractDuration = Internal.subtractDuration;
  */
 export const add = Internal.add;
 /**
- * Subtract the given `amount` of `unit`'s from a `DateTime`.
+ * Subtracts the given `amount` of `unit` from a `DateTime`.
  *
  * **Example** (Subtracting date and time parts)
  *
@@ -1717,7 +1802,8 @@ export const nearest = Internal.nearest;
  */
 export const format = Internal.format;
 /**
- * Format a `DateTime` as a string using the `DateTimeFormat` API.
+ * Formats a `DateTime` with `Intl.DateTimeFormat` using the system local time
+ * zone and locale.
  *
  * **Details**
  *
@@ -1747,7 +1833,7 @@ export const format = Internal.format;
  */
 export const formatLocal = Internal.formatLocal;
 /**
- * Format a `DateTime` as a string using the `DateTimeFormat` API.
+ * Formats a `DateTime` with `Intl.DateTimeFormat` using the UTC time zone.
  *
  * **Details**
  *
@@ -1780,7 +1866,17 @@ export const formatLocal = Internal.formatLocal;
  */
 export const formatUtc = Internal.formatUtc;
 /**
- * Format a `DateTime` as a string using the `DateTimeFormat` API.
+ * Formats a `DateTime` as a string using the `Intl.DateTimeFormat` API.
+ *
+ * **When to use**
+ *
+ * Use when you already have an `Intl.DateTimeFormat` and want it to control the
+ * locale, time zone, and formatting options.
+ *
+ * **Details**
+ *
+ * The formatter receives the `DateTime` epoch milliseconds. Any time zone
+ * conversion comes from the supplied formatter.
  *
  * **Example** (Formatting DateTime values with custom formatters)
  *
@@ -1800,15 +1896,18 @@ export const formatUtc = Internal.formatUtc;
  * })
  *
  * const formatted = DateTime.formatIntl(dt, formatter)
- * console.log(formatted) // "15. Juni 2024, 16:30"
+ * console.log(formatted.length > 0) // true
  * ```
  *
+ * @see {@link formatUtc} for formatting with options forced to UTC
+ * @see {@link formatIso} for stable ISO formatting
+ *
  * @category formatting
  * @since 3.6.0
  */
 export const formatIntl = Internal.formatIntl;
 /**
- * Format a `DateTime` as a UTC ISO string.
+ * Formats a `DateTime` as a UTC ISO string.
  *
  * **Details**
  *
@@ -1833,7 +1932,7 @@ export const formatIntl = Internal.formatIntl;
  */
 export const formatIso = Internal.formatIso;
 /**
- * Format a `DateTime` as a time zone adjusted ISO date string.
+ * Formats a `DateTime` as a time zone adjusted ISO date string.
  *
  * **Details**
  *
@@ -1858,7 +1957,7 @@ export const formatIso = Internal.formatIso;
  */
 export const formatIsoDate = Internal.formatIsoDate;
 /**
- * Format a `DateTime` as a UTC ISO date string.
+ * Formats a `DateTime` as a UTC ISO date string.
  *
  * **Details**
  *
@@ -1883,7 +1982,7 @@ export const formatIsoDate = Internal.formatIsoDate;
  */
 export const formatIsoDateUtc = Internal.formatIsoDateUtc;
 /**
- * Format a `DateTime.Zoned` as an ISO string with an offset.
+ * Formats a `DateTime.Zoned` as an ISO string with an offset.
  *
  * **Details**
  *
@@ -1909,7 +2008,7 @@ export const formatIsoDateUtc = Internal.formatIsoDateUtc;
  */
 export const formatIsoOffset = Internal.formatIsoOffset;
 /**
- * Format a `DateTime.Zoned` as a string.
+ * Formats a `DateTime.Zoned` as a string.
  *
  * **Details**
  *