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

package/src/DateTime.ts

@@ -444,13 +444,28 @@ export type Disambiguation = "compatible" | "earlier" | "later" | "reject"
 /**
  * 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: (u: unknown) => u is DateTime = 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
@@ -458,7 +473,15 @@ export const isDateTime: (u: unknown) => u is DateTime = Internal.isDateTime
 export const isTimeZone: (u: unknown) => u is TimeZone = 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
@@ -466,7 +489,15 @@ export const isTimeZone: (u: unknown) => u is TimeZone = Internal.isTimeZone
 export const isTimeZoneOffset: (u: unknown) => u is TimeZone.Offset = 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
@@ -474,7 +505,15 @@ export const isTimeZoneOffset: (u: unknown) => u is TimeZone.Offset = Internal.i
 export const isTimeZoneNamed: (u: unknown) => u is TimeZone.Named = 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
@@ -482,7 +521,15 @@ export const isTimeZoneNamed: (u: unknown) => u is TimeZone.Named = Internal.isT
 export const isUtc: (self: DateTime) => self is Utc = 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
@@ -494,7 +541,7 @@ export const isZoned: (self: DateTime) => self is Zoned = Internal.isZoned
 // =============================================================================
 
 /**
- * An `Equivalence` for comparing two `DateTime` values for equality.
+ * Provides an `Equivalence` for comparing two `DateTime` values for equality.
  *
  * **Details**
  *
@@ -520,7 +567,7 @@ export const isZoned: (self: DateTime) => self is Zoned = Internal.isZoned
 export const Equivalence: Equ.Equivalence<DateTime> = Internal.Equivalence
 
 /**
- * An `Order` for comparing and sorting `DateTime` values.
+ * Provides an `Order` for comparing and sorting `DateTime` values.
  *
  * **Details**
  *
@@ -548,7 +595,7 @@ export const Equivalence: Equ.Equivalence<DateTime> = Internal.Equivalence
 export const Order: order.Order<DateTime> = Internal.Order
 
 /**
- * Clamp a `DateTime` between a minimum and maximum value.
+ * Returns a `DateTime` constrained between a minimum and maximum value.
  *
  * **Details**
  *
@@ -569,12 +616,12 @@ export const Order: order.Order<DateTime> = Internal.Order
  * // clamped equals max (2024-12-31)
  * ```
  *
- * @category instances
+ * @category ordering
  * @since 3.6.0
  */
 export const clamp: {
   /**
-   * Clamp a `DateTime` between a minimum and maximum value.
+   * Returns a `DateTime` constrained between a minimum and maximum value.
    *
    * **Details**
    *
@@ -595,12 +642,12 @@ export const clamp: {
    * // clamped equals max (2024-12-31)
    * ```
    *
-   * @category instances
+   * @category ordering
    * @since 3.6.0
    */
   <Min extends DateTime, Max extends DateTime>(options: { readonly minimum: Min; readonly maximum: Max }): <A extends DateTime>(self: A) => A | Min | Max
   /**
-   * Clamp a `DateTime` between a minimum and maximum value.
+   * Returns a `DateTime` constrained between a minimum and maximum value.
    *
    * **Details**
    *
@@ -621,7 +668,7 @@ export const clamp: {
    * // clamped equals max (2024-12-31)
    * ```
    *
-   * @category instances
+   * @category ordering
    * @since 3.6.0
    */
   <A extends DateTime, Min extends DateTime, Max extends DateTime>(self: A, options: { readonly minimum: Min; readonly maximum: Max }): A | Min | Max
@@ -726,7 +773,7 @@ export const makeZonedUnsafe: (input: DateTime.Input, options?: {
 }) => Zoned = 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**
  *
@@ -774,7 +821,7 @@ export const makeZoned: (
 ) => Option.Option<Zoned> = Internal.makeZoned
 
 /**
- * Creates a `DateTime` from supported input values.
+ * Creates a `DateTime` safely from supported input values.
  *
  * **Details**
  *
@@ -815,7 +862,7 @@ export const makeZoned: (
 export const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTime.PreserveZone<A>> = 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**
  *
@@ -847,7 +894,7 @@ export const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTim
 export const makeZonedFromString: (input: string) => Option.Option<Zoned> = 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)
  *
@@ -885,7 +932,7 @@ export const now: Effect.Effect<Utc> = Internal.now
 export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
 
 /**
- * Get the current time using `Date.now`.
+ * Gets the current time using `Date.now`.
  *
  * **Details**
  *
@@ -911,7 +958,16 @@ export const nowUnsafe: LazyArg<Utc> = Internal.nowUnsafe
 // =============================================================================
 
 /**
- * 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)
  *
@@ -932,7 +988,7 @@ export const nowUnsafe: LazyArg<Utc> = Internal.nowUnsafe
 export const toUtc: (self: DateTime) => Utc = 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)
  *
@@ -953,7 +1009,7 @@ export const toUtc: (self: DateTime) => Utc = Internal.toUtc
  */
 export const setZone: {
   /**
-   * 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)
    *
@@ -980,7 +1036,7 @@ export const setZone: {
    }
   ): (self: DateTime) => Zoned
   /**
-   * 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)
    *
@@ -1010,7 +1066,7 @@ export const setZone: {
 } = Internal.setZone
 
 /**
- * Add a fixed offset time zone to a `DateTime`.
+ * Adds a fixed offset time zone to a `DateTime`.
  *
  * **Details**
  *
@@ -1034,7 +1090,7 @@ export const setZone: {
  */
 export const setZoneOffset: {
   /**
-   * Add a fixed offset time zone to a `DateTime`.
+   * Adds a fixed offset time zone to a `DateTime`.
    *
    * **Details**
    *
@@ -1064,7 +1120,7 @@ export const setZoneOffset: {
    }
   ): (self: DateTime) => Zoned
   /**
-   * Add a fixed offset time zone to a `DateTime`.
+   * Adds a fixed offset time zone to a `DateTime`.
    *
    * **Details**
    *
@@ -1097,7 +1153,7 @@ 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**
  *
@@ -1150,7 +1206,7 @@ export const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named = Internal.
 export const zoneMakeOffset: (offset: number) => TimeZone.Offset = 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**
  *
@@ -1174,7 +1230,7 @@ export const zoneMakeOffset: (offset: number) => TimeZone.Offset = Internal.zone
 export const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named> = 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**
  *
@@ -1221,7 +1277,7 @@ export const zoneMakeNamedEffect: (zoneId: string) => Effect.Effect<TimeZone.Nam
 export const zoneMakeLocal: () => TimeZone.Named = Internal.zoneMakeLocal
 
 /**
- * Try to parse a `TimeZone` from a string.
+ * Tries to parse a `TimeZone` from a string safely.
  *
  * **Details**
  *
@@ -1247,7 +1303,7 @@ export const zoneMakeLocal: () => TimeZone.Named = Internal.zoneMakeLocal
 export const zoneFromString: (zone: string) => Option.Option<TimeZone> = Internal.zoneFromString
 
 /**
- * Format a `TimeZone` as a string.
+ * Formats a `TimeZone` as a string.
  *
  * **Example** (Formatting time zones)
  *
@@ -1267,7 +1323,7 @@ export const zoneFromString: (zone: string) => Option.Option<TimeZone> = Interna
 export const zoneToString: (self: TimeZone) => string = 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)
@@ -1287,7 +1343,7 @@ export const zoneToString: (self: TimeZone) => string = Internal.zoneToString
  */
 export const setZoneNamed: {
   /**
-   * 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)
@@ -1313,7 +1369,7 @@ export const setZoneNamed: {
    }
   ): (self: DateTime) => Option.Option<Zoned>
   /**
-   * 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)
@@ -1342,7 +1398,7 @@ 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)
@@ -1362,7 +1418,7 @@ export const setZoneNamed: {
  */
 export const setZoneNamedUnsafe: {
   /**
-   * 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)
@@ -1388,7 +1444,7 @@ export const setZoneNamedUnsafe: {
    }
   ): (self: DateTime) => Zoned
   /**
-   * 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)
@@ -1421,7 +1477,7 @@ export const setZoneNamedUnsafe: {
 // =============================================================================
 
 /**
- * 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**
@@ -1453,7 +1509,7 @@ export const distance: {
   // =============================================================================
 
   /**
-   * 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**
@@ -1485,7 +1541,7 @@ export const distance: {
   // =============================================================================
 
   /**
-   * 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**
@@ -1633,7 +1689,7 @@ 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)
  *
@@ -1652,7 +1708,7 @@ export const max: {
  */
 export const isGreaterThan: {
   /**
-   * 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)
    *
@@ -1671,7 +1727,7 @@ export const isGreaterThan: {
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
-   * 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)
    *
@@ -1692,7 +1748,7 @@ 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)
  *
@@ -1713,7 +1769,7 @@ export const isGreaterThan: {
  */
 export const isGreaterThanOrEqualTo: {
   /**
-   * 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)
    *
@@ -1734,7 +1790,7 @@ export const isGreaterThanOrEqualTo: {
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
-   * 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)
    *
@@ -1757,7 +1813,7 @@ 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)
  *
@@ -1776,7 +1832,7 @@ export const isGreaterThanOrEqualTo: {
  */
 export const isLessThan: {
   /**
-   * 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)
    *
@@ -1795,7 +1851,7 @@ export const isLessThan: {
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
-   * 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)
    *
@@ -1816,7 +1872,7 @@ 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)
  *
@@ -1837,7 +1893,7 @@ export const isLessThan: {
  */
 export const isLessThanOrEqualTo: {
   /**
-   * 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)
    *
@@ -1858,7 +1914,7 @@ export const isLessThanOrEqualTo: {
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
-   * 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)
    *
@@ -1881,7 +1937,7 @@ 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)
  *
@@ -1900,7 +1956,7 @@ export const isLessThanOrEqualTo: {
  */
 export const between: {
   /**
-   * 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)
    *
@@ -1919,7 +1975,7 @@ export const between: {
    */
   (options: { minimum: DateTime; maximum: DateTime }): (self: DateTime) => boolean
   /**
-   * 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)
    *
@@ -1940,7 +1996,7 @@ 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**
  *
@@ -1964,7 +2020,7 @@ export const between: {
 export const isFuture: (self: DateTime) => Effect.Effect<boolean> = 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**
  *
@@ -1988,7 +2044,7 @@ export const isFuture: (self: DateTime) => Effect.Effect<boolean> = Internal.isF
 export const isFutureUnsafe: (self: DateTime) => boolean = 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**
  *
@@ -2012,7 +2068,7 @@ export const isFutureUnsafe: (self: DateTime) => boolean = Internal.isFutureUnsa
 export const isPast: (self: DateTime) => Effect.Effect<boolean> = 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**
  *
@@ -2040,7 +2096,7 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
 // =============================================================================
 
 /**
- * Get the UTC `Date` of a `DateTime`.
+ * Gets the UTC `Date` of a `DateTime`.
  *
  * **Details**
  *
@@ -2065,7 +2121,7 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
 export const toDateUtc: (self: DateTime) => Date = 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**
  *
@@ -2092,7 +2148,7 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
 export const toDate: (self: DateTime) => Date = 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**
  *
@@ -2118,7 +2174,7 @@ export const toDate: (self: DateTime) => Date = Internal.toDate
 export const zonedOffset: (self: Zoned) => number = 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**
  *
@@ -2143,7 +2199,7 @@ export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
 export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
 
 /**
- * Get the milliseconds since the Unix epoch of a `DateTime`.
+ * Gets the milliseconds since the Unix epoch of a `DateTime`.
  *
  * **Details**
  *
@@ -2166,7 +2222,7 @@ export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
 export const toEpochMillis: (self: DateTime) => number = 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)
@@ -2194,7 +2250,7 @@ export const removeTime: (self: DateTime) => Utc = Internal.removeTime
 // =============================================================================
 
 /**
- * Get the different parts of a `DateTime` as an object.
+ * Gets the time-zone-adjusted parts of a `DateTime` as an object.
  *
  * **Details**
  *
@@ -2227,7 +2283,7 @@ export const removeTime: (self: DateTime) => Utc = Internal.removeTime
 export const toParts: (self: DateTime) => DateTime.PartsWithWeekday = Internal.toParts
 
 /**
- * Get the different parts of a `DateTime` as an object.
+ * Gets the UTC parts of a `DateTime` as an object.
  *
  * **Details**
  *
@@ -2253,7 +2309,7 @@ export const toParts: (self: DateTime) => DateTime.PartsWithWeekday = Internal.t
 export const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday = Internal.toPartsUtc
 
 /**
- * Get a part of a `DateTime` as a number.
+ * Gets one UTC part of a `DateTime` as a number.
  *
  * **Details**
  *
@@ -2274,7 +2330,7 @@ export const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday = Interna
  */
 export const getPartUtc: {
   /**
-   * Get a part of a `DateTime` as a number.
+   * Gets one UTC part of a `DateTime` as a number.
    *
    * **Details**
    *
@@ -2295,7 +2351,7 @@ export const getPartUtc: {
    */
   (part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
   /**
-   * Get a part of a `DateTime` as a number.
+   * Gets one UTC part of a `DateTime` as a number.
    *
    * **Details**
    *
@@ -2318,7 +2374,7 @@ 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**
  *
@@ -2341,7 +2397,7 @@ export const getPartUtc: {
  */
 export const getPart: {
   /**
-   * Get a part of a `DateTime` as a number.
+   * Gets one time-zone-adjusted part of a `DateTime` as a number.
    *
    * **Details**
    *
@@ -2364,7 +2420,7 @@ export const getPart: {
    */
   (part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
   /**
-   * Get a part of a `DateTime` as a number.
+   * Gets one time-zone-adjusted part of a `DateTime` as a number.
    *
    * **Details**
    *
@@ -2389,7 +2445,7 @@ export const getPart: {
 } = Internal.getPart
 
 /**
- * Set the different parts of a `DateTime` as an object.
+ * Sets time-zone-adjusted parts on a `DateTime`.
  *
  * **Details**
  *
@@ -2415,7 +2471,7 @@ export const getPart: {
  */
 export const setParts: {
   /**
-   * Set the different parts of a `DateTime` as an object.
+   * Sets time-zone-adjusted parts on a `DateTime`.
    *
    * **Details**
    *
@@ -2441,7 +2497,7 @@ export const setParts: {
    */
   (parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => A
   /**
-   * Set the different parts of a `DateTime` as an object.
+   * Sets time-zone-adjusted parts on a `DateTime`.
    *
    * **Details**
    *
@@ -2469,7 +2525,7 @@ export const setParts: {
 } = Internal.setParts
 
 /**
- * Set the different parts of a `DateTime` as an object.
+ * Sets UTC parts on a `DateTime`.
  *
  * **Details**
  *
@@ -2494,7 +2550,7 @@ export const setParts: {
  */
 export const setPartsUtc: {
   /**
-   * Set the different parts of a `DateTime` as an object.
+   * Sets UTC parts on a `DateTime`.
    *
    * **Details**
    *
@@ -2519,7 +2575,7 @@ export const setPartsUtc: {
    */
   (parts: Partial<DateTime.PartsWithWeekday>): <A extends DateTime>(self: A) => A
   /**
-   * Set the different parts of a `DateTime` as an object.
+   * Sets UTC parts on a `DateTime`.
    *
    * **Details**
    *
@@ -2583,7 +2639,7 @@ export class CurrentTimeZone extends Context.Service<CurrentTimeZone, TimeZone>(
 ) {}
 
 /**
- * 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)
@@ -2606,7 +2662,7 @@ export const setZoneCurrent = (self: DateTime): Effect.Effect<Zoned, never, Curr
   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)
  *
@@ -2625,7 +2681,7 @@ export const setZoneCurrent = (self: DateTime): Effect.Effect<Zoned, never, Curr
  */
 export const withCurrentZone: {
   /**
-   * Provide the `CurrentTimeZone` to an effect.
+   * Provides the `CurrentTimeZone` to an effect.
    *
    * **Example** (Providing the current time zone)
    *
@@ -2644,7 +2700,7 @@ export const withCurrentZone: {
    */
   (value: TimeZone): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
   /**
-   * Provide the `CurrentTimeZone` to an effect.
+   * Provides the `CurrentTimeZone` to an effect.
    *
    * **Example** (Providing the current time zone)
    *
@@ -2665,7 +2721,7 @@ export const withCurrentZone: {
 } = 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)
@@ -2688,7 +2744,7 @@ export const withCurrentZoneLocal = <A, E, R>(
   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)
  *
@@ -2706,7 +2762,7 @@ export const withCurrentZoneLocal = <A, E, R>(
  */
 export const withCurrentZoneOffset: {
   /**
-   * 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)
    *
@@ -2726,7 +2782,7 @@ export const withCurrentZoneOffset: {
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
   /**
-   * 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)
    *
@@ -2750,7 +2806,7 @@ export const withCurrentZoneOffset: {
 )
 
 /**
- * Provide the `CurrentTimeZone` to an effect using an IANA time zone
+ * Provides the `CurrentTimeZone` to an effect using an IANA time zone
  * identifier.
  *
  * **Details**
@@ -2773,7 +2829,7 @@ export const withCurrentZoneOffset: {
  */
 export const withCurrentZoneNamed: {
   /**
-   * Provide the `CurrentTimeZone` to an effect using an IANA time zone
+   * Provides the `CurrentTimeZone` to an effect using an IANA time zone
    * identifier.
    *
    * **Details**
@@ -2798,7 +2854,7 @@ export const withCurrentZoneNamed: {
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<A, E | IllegalArgumentError, Exclude<R, CurrentTimeZone>>
   /**
-   * Provide the `CurrentTimeZone` to an effect using an IANA time zone
+   * Provides the `CurrentTimeZone` to an effect using an IANA time zone
    * identifier.
    *
    * **Details**
@@ -2830,7 +2886,7 @@ export const withCurrentZoneNamed: {
 )
 
 /**
- * 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)
  *
@@ -2853,7 +2909,12 @@ export const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone> = Ef
 // =============================================================================
 
 /**
- * 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**
  *
@@ -2886,7 +2947,12 @@ export const mutate: {
   // =============================================================================
 
   /**
-   * 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**
    *
@@ -2924,7 +2990,12 @@ export const mutate: {
   // =============================================================================
 
   /**
-   * 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**
    *
@@ -2961,7 +3032,12 @@ 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)
  *
@@ -2984,7 +3060,12 @@ export const mutate: {
  */
 export const mutateUtc: {
   /**
-   * 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)
    *
@@ -3007,7 +3088,12 @@ export const mutateUtc: {
    */
   (f: (date: Date) => void): <A extends DateTime>(self: A) => A
   /**
-   * 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)
    *
@@ -3032,7 +3118,7 @@ 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)
@@ -3051,7 +3137,7 @@ export const mutateUtc: {
  */
 export const mapEpochMillis: {
   /**
-   * 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)
@@ -3070,7 +3156,7 @@ export const mapEpochMillis: {
    */
   (f: (millis: number) => number): <A extends DateTime>(self: A) => A
   /**
-   * 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)
@@ -3352,7 +3438,23 @@ export const match: {
 // =============================================================================
 
 /**
- * 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)
  *
@@ -3365,6 +3467,9 @@ export const 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
  */
@@ -3374,7 +3479,23 @@ export const addDuration: {
   // =============================================================================
 
   /**
-   * 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)
    *
@@ -3387,6 +3508,9 @@ export const addDuration: {
    * )
    * ```
    *
+   * @see {@link add} for calendar-aware date/time part arithmetic
+   * @see {@link subtractDuration} for subtracting an elapsed duration
+   *
    * @category math
    * @since 3.6.0
    */
@@ -3396,7 +3520,23 @@ export const addDuration: {
   // =============================================================================
 
   /**
-   * 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)
    *
@@ -3409,6 +3549,9 @@ export const addDuration: {
    * )
    * ```
    *
+   * @see {@link add} for calendar-aware date/time part arithmetic
+   * @see {@link subtractDuration} for subtracting an elapsed duration
+   *
    * @category math
    * @since 3.6.0
    */
@@ -3416,7 +3559,7 @@ export const addDuration: {
 } = Internal.addDuration
 
 /**
- * Subtract the given `Duration` from a `DateTime`.
+ * Subtracts the given `Duration` from a `DateTime`.
  *
  * **Example** (Subtracting durations)
  *
@@ -3434,7 +3577,7 @@ export const addDuration: {
  */
 export const subtractDuration: {
   /**
-   * Subtract the given `Duration` from a `DateTime`.
+   * Subtracts the given `Duration` from a `DateTime`.
    *
    * **Example** (Subtracting durations)
    *
@@ -3452,7 +3595,7 @@ export const subtractDuration: {
    */
   (duration: Duration.Input): <A extends DateTime>(self: A) => A
   /**
-   * Subtract the given `Duration` from a `DateTime`.
+   * Subtracts the given `Duration` from a `DateTime`.
    *
    * **Example** (Subtracting durations)
    *
@@ -3472,7 +3615,7 @@ 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**
  *
@@ -3495,7 +3638,7 @@ export const subtractDuration: {
  */
 export const add: {
   /**
-   * Add the given `amount` of `unit`'s to a `DateTime`.
+   * Adds the given `amount` of `unit` to a `DateTime`.
    *
    * **Details**
    *
@@ -3518,7 +3661,7 @@ export const add: {
    */
   (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A
   /**
-   * Add the given `amount` of `unit`'s to a `DateTime`.
+   * Adds the given `amount` of `unit` to a `DateTime`.
    *
    * **Details**
    *
@@ -3543,7 +3686,7 @@ 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)
  *
@@ -3561,7 +3704,7 @@ export const add: {
  */
 export const subtract: {
   /**
-   * 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)
    *
@@ -3579,7 +3722,7 @@ export const subtract: {
    */
   (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A
   /**
-   * 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)
    *
@@ -3971,7 +4114,8 @@ 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**
  *
@@ -4001,7 +4145,8 @@ export const format: {
  */
 export const formatLocal: {
   /**
-   * 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**
    *
@@ -4037,7 +4182,8 @@ export const formatLocal: {
      | undefined
   ): (self: DateTime) => string
   /**
-   * 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**
    *
@@ -4076,7 +4222,7 @@ 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**
  *
@@ -4109,7 +4255,7 @@ export const formatLocal: {
  */
 export const formatUtc: {
   /**
-   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   * Formats a `DateTime` with `Intl.DateTimeFormat` using the UTC time zone.
    *
    * **Details**
    *
@@ -4148,7 +4294,7 @@ export const formatUtc: {
      | undefined
   ): (self: DateTime) => string
   /**
-   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   * Formats a `DateTime` with `Intl.DateTimeFormat` using the UTC time zone.
    *
    * **Details**
    *
@@ -4190,7 +4336,17 @@ 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)
  *
@@ -4210,15 +4366,28 @@ export const 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: {
   /**
-   * 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)
    *
@@ -4238,15 +4407,28 @@ export const formatIntl: {
    * })
    *
    * 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
    */
   (format: Intl.DateTimeFormat): (self: DateTime) => string
   /**
-   * 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)
    *
@@ -4266,9 +4448,12 @@ export const formatIntl: {
    * })
    *
    * 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
    */
@@ -4276,7 +4461,7 @@ export const formatIntl: {
 } = Internal.formatIntl
 
 /**
- * Format a `DateTime` as a UTC ISO string.
+ * Formats a `DateTime` as a UTC ISO string.
  *
  * **Details**
  *
@@ -4302,7 +4487,7 @@ export const formatIntl: {
 export const formatIso: (self: DateTime) => string = 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**
  *
@@ -4328,7 +4513,7 @@ export const formatIso: (self: DateTime) => string = Internal.formatIso
 export const formatIsoDate: (self: DateTime) => string = Internal.formatIsoDate
 
 /**
- * Format a `DateTime` as a UTC ISO date string.
+ * Formats a `DateTime` as a UTC ISO date string.
  *
  * **Details**
  *
@@ -4354,7 +4539,7 @@ export const formatIsoDate: (self: DateTime) => string = Internal.formatIsoDate
 export const formatIsoDateUtc: (self: DateTime) => string = 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**
  *
@@ -4381,7 +4566,7 @@ export const formatIsoDateUtc: (self: DateTime) => string = Internal.formatIsoDa
 export const formatIsoOffset: (self: DateTime) => string = Internal.formatIsoOffset
 
 /**
- * Format a `DateTime.Zoned` as a string.
+ * Formats a `DateTime.Zoned` as a string.
  *
  * **Details**
  *