effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/DateTime.ts

@@ -457,7 +457,7 @@ export type Disambiguation = "compatible" | "earlier" | "later" | "reject"
 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**
  *
@@ -473,7 +473,7 @@ 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**
  *
@@ -489,7 +489,7 @@ 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**
  *
@@ -505,7 +505,7 @@ 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**
  *
@@ -521,7 +521,7 @@ 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**
  *
@@ -541,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**
  *
@@ -567,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**
  *
@@ -595,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**
  *
@@ -616,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**
    *
@@ -642,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**
    *
@@ -668,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
@@ -773,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**
  *
@@ -821,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**
  *
@@ -862,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**
  *
@@ -894,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)
  *
@@ -932,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**
  *
@@ -958,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)
  *
@@ -979,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)
  *
@@ -1000,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)
    *
@@ -1027,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)
    *
@@ -1057,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**
  *
@@ -1081,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**
    *
@@ -1111,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**
    *
@@ -1144,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**
  *
@@ -1197,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**
  *
@@ -1221,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**
  *
@@ -1268,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**
  *
@@ -1294,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)
  *
@@ -1314,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)
@@ -1334,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)
@@ -1360,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)
@@ -1389,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)
@@ -1409,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)
@@ -1435,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)
@@ -1468,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**
@@ -1500,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**
@@ -1532,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**
@@ -1680,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)
  *
@@ -1699,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)
    *
@@ -1718,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)
    *
@@ -1739,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)
  *
@@ -1760,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)
    *
@@ -1781,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)
    *
@@ -1804,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)
  *
@@ -1823,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)
    *
@@ -1842,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)
    *
@@ -1863,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)
  *
@@ -1884,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)
    *
@@ -1905,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)
    *
@@ -1928,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)
  *
@@ -1947,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)
    *
@@ -1966,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)
    *
@@ -1987,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**
  *
@@ -2011,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**
  *
@@ -2035,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**
  *
@@ -2059,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**
  *
@@ -2087,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**
  *
@@ -2112,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**
  *
@@ -2139,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**
  *
@@ -2165,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**
  *
@@ -2190,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**
  *
@@ -2213,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)
@@ -2241,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**
  *
@@ -2274,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**
  *
@@ -2300,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**
  *
@@ -2321,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**
    *
@@ -2342,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**
    *
@@ -2365,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**
  *
@@ -2388,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**
    *
@@ -2411,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**
    *
@@ -2436,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**
  *
@@ -2462,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**
    *
@@ -2488,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**
    *
@@ -2516,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**
  *
@@ -2541,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**
    *
@@ -2566,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**
    *
@@ -2630,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)
@@ -2653,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)
  *
@@ -2672,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)
    *
@@ -2691,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)
    *
@@ -2712,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)
@@ -2735,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)
  *
@@ -2753,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)
    *
@@ -2773,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)
    *
@@ -2797,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**
@@ -2820,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**
@@ -2845,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**
@@ -2877,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)
  *
@@ -2900,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**
  *
@@ -2933,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**
    *
@@ -2971,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**
    *
@@ -3008,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)
  *
@@ -3031,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)
    *
@@ -3054,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)
    *
@@ -3079,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)
@@ -3098,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)
@@ -3117,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)
@@ -3399,7 +3438,7 @@ export const match: {
 // =============================================================================
 
 /**
- * Add the given `Duration` to a `DateTime`.
+ * Adds the given `Duration` to a `DateTime`.
  *
  * **When to use**
  *
@@ -3440,7 +3479,7 @@ export const addDuration: {
   // =============================================================================
 
   /**
-   * Add the given `Duration` to a `DateTime`.
+   * Adds the given `Duration` to a `DateTime`.
    *
    * **When to use**
    *
@@ -3481,7 +3520,7 @@ export const addDuration: {
   // =============================================================================
 
   /**
-   * Add the given `Duration` to a `DateTime`.
+   * Adds the given `Duration` to a `DateTime`.
    *
    * **When to use**
    *
@@ -3520,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)
  *
@@ -3538,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)
    *
@@ -3556,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)
    *
@@ -3576,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**
  *
@@ -3599,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**
    *
@@ -3622,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**
    *
@@ -3647,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)
  *
@@ -3665,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)
    *
@@ -3683,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)
    *
@@ -4075,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**
  *
@@ -4105,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**
    *
@@ -4141,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**
    *
@@ -4180,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**
  *
@@ -4213,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**
    *
@@ -4252,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**
    *
@@ -4419,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**
  *
@@ -4445,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**
  *
@@ -4471,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**
  *
@@ -4497,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**
  *
@@ -4524,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**
  *