effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/DateTime.ts

@@ -1,4 +1,53 @@
 /**
+ * The `DateTime` module provides immutable data types and utilities for working
+ * with instants, UTC date-times, zoned date-times, and time zones. A
+ * `DateTime` is always an absolute point in time, represented internally by
+ * epoch milliseconds, and may also carry a `TimeZone` for zone-aware calendar
+ * parts and formatting.
+ *
+ * **Mental model**
+ *
+ * - `DateTime` is a discriminated union: `Utc | Zoned`
+ * - `Utc` stores an absolute instant without an associated time zone
+ * - `Zoned` stores the same kind of absolute instant plus a `TimeZone`
+ * - Time zones can be fixed offsets or named IANA zones such as `"Europe/Rome"`
+ * - Comparison and ordering use the instant, so two values in different zones
+ *   can still be equivalent
+ * - Calendar parts and formatted output depend on whether you ask for UTC parts
+ *   or zone-adjusted parts
+ *
+ * **Common tasks**
+ *
+ * - Construct values: {@link make}, {@link makeUnsafe}, {@link makeZoned}, {@link makeZonedUnsafe}
+ * - Get the current instant: {@link now}, {@link nowInCurrentZone}
+ * - Create time zones: {@link zoneMakeOffset}, {@link zoneMakeNamed}, {@link zoneFromString}
+ * - Attach or change zones: {@link setZone}, {@link setZoneNamed}, {@link setZoneCurrent}, {@link toUtc}
+ * - Convert to platform values or parts: {@link toDate}, {@link toDateUtc}, {@link toEpochMillis}, {@link toParts}, {@link toPartsUtc}
+ * - Compare and bound values: {@link Equivalence}, {@link Order}, {@link distance}, {@link min}, {@link max}, {@link clamp}, {@link between}
+ * - Transform values: {@link add}, {@link subtract}, {@link startOf}, {@link endOf}, {@link nearest}, {@link setParts}, {@link mutate}
+ * - Format values: {@link format}, {@link formatUtc}, {@link formatLocal}, {@link formatIntl}, {@link formatIso}, {@link formatIsoZoned}
+ * - Provide an application time zone: {@link CurrentTimeZone}, {@link withCurrentZone}, {@link layerCurrentZone}
+ *
+ * **Gotchas**
+ *
+ * - `make` and `makeZoned` return `Option`; unsafe constructors throw on invalid
+ *   input
+ * - `DateTime` equality is instant-based, not display-time-based
+ * - `setZone` changes the zone used for local parts and formatting without
+ *   changing the represented instant
+ * - Use `adjustForTimeZone` with {@link makeZoned} when input parts should be
+ *   interpreted as wall-clock time in the target zone
+ * - Daylight-saving gaps and repeated local times are resolved with
+ *   `Disambiguation`
+ * - Prefer the Clock-backed {@link now} and `CurrentTimeZone` services in
+ *   Effect workflows; unsafe helpers read from the host environment directly
+ *
+ * **See also**
+ *
+ * - {@link DateTime} for the UTC/zoned data model
+ * - {@link TimeZone} for offset and named time-zone values
+ * - {@link Disambiguation} for daylight-saving ambiguity handling
+ *
  * @since 3.6.0
  */
 import type { IllegalArgumentError } from "./Cause.ts"
@@ -22,14 +71,19 @@ const TimeZoneTypeId = Internal.TimeZoneTypeId
  * A `DateTime` represents a point in time. It can optionally have a time zone
  * associated with it.
  *
- * @since 3.6.0
  * @category models
+ * @since 3.6.0
  */
 export type DateTime = Utc | Zoned
 
 /**
- * @since 3.6.0
+ * Represents a `DateTime` stored as an absolute UTC instant with no associated
+ * time zone.
+ *
+ * Use `DateTime.isUtc` to narrow a `DateTime` to this variant.
+ *
  * @category models
+ * @since 3.6.0
  */
 export interface Utc extends DateTime.Proto {
   readonly _tag: "Utc"
@@ -38,8 +92,14 @@ export interface Utc extends DateTime.Proto {
 }
 
 /**
- * @since 3.6.0
+ * Represents a `DateTime` with an associated `TimeZone`.
+ *
+ * A zoned value still represents an absolute instant through
+ * `epochMilliseconds`, while the time zone is used for wall-clock parts,
+ * formatting, and zone-aware transformations.
+ *
  * @category models
+ * @since 3.6.0
  */
 export interface Zoned extends DateTime.Proto {
   readonly _tag: "Zoned"
@@ -51,31 +111,54 @@ export interface Zoned extends DateTime.Proto {
 }
 
 /**
+ * Companion namespace containing the public helper types used by `DateTime`
+ * constructors, parts APIs, formatting, and date/time arithmetic.
+ *
  * @since 3.6.0
- * @category models
  */
 export declare namespace DateTime {
   /**
-   * @since 3.6.0
+   * Input accepted by `DateTime.make`, `DateTime.makeUnsafe`, and the zoned
+   * constructors.
+   *
+   * Includes existing `DateTime` values, partial date parts, epoch-millisecond
+   * objects, epoch milliseconds, JavaScript `Date` instances, and parseable date
+   * strings.
+   *
    * @category models
+   * @since 3.6.0
    */
   export type Input = DateTime | Partial<Parts> | Instant | InstantWithZone | Date | number | string
 
   /**
-   * @since 3.6.0
+   * Type-level helper used by constructors to preserve a zoned input.
+   *
+   * When the input type is `DateTime.Zoned`, the result type is
+   * `DateTime.Zoned`; otherwise the result type is `DateTime.Utc`.
+   *
    * @category models
+   * @since 3.6.0
    */
   export type PreserveZone<A extends DateTime.Input> = A extends Zoned ? Zoned : Utc
 
   /**
-   * @since 3.6.0
+   * Date and time unit name accepted by `DateTime` rounding and arithmetic
+   * APIs.
+   *
+   * Includes both singular units, such as `"day"`, and plural units, such as
+   * `"days"`.
+   *
    * @category models
+   * @since 3.6.0
    */
   export type Unit = UnitSingular | UnitPlural
 
   /**
-   * @since 3.6.0
+   * Singular date and time unit names used by rounding APIs such as
+   * `DateTime.startOf`, `DateTime.endOf`, and `DateTime.nearest`.
+   *
    * @category models
+   * @since 3.6.0
    */
   export type UnitSingular =
     | "millisecond"
@@ -88,8 +171,11 @@ export declare namespace DateTime {
     | "year"
 
   /**
-   * @since 3.6.0
+   * Plural date and time unit names used by `DateTime.PartsForMath` for
+   * amount-based arithmetic.
+   *
    * @category models
+   * @since 3.6.0
    */
   export type UnitPlural =
     | "milliseconds"
@@ -102,8 +188,14 @@ export declare namespace DateTime {
     | "years"
 
   /**
-   * @since 3.6.0
+   * Calendar and time components of a `DateTime`, including the weekday.
+   *
+   * `month` is one-based (`1` for January through `12` for December), and
+   * `weekDay` follows JavaScript `Date#getUTCDay` numbering (`0` for Sunday
+   * through `6` for Saturday).
+   *
    * @category models
+   * @since 3.6.0
    */
   export interface PartsWithWeekday {
     readonly millisecond: number
@@ -117,8 +209,12 @@ export declare namespace DateTime {
   }
 
   /**
-   * @since 3.6.0
+   * Calendar and time components of a `DateTime`, without weekday information.
+   *
+   * `month` is one-based (`1` for January through `12` for December).
+   *
    * @category models
+   * @since 3.6.0
    */
   export interface Parts {
     readonly millisecond: number
@@ -131,8 +227,12 @@ export declare namespace DateTime {
   }
 
   /**
-   * @since 3.6.0
+   * Plural amount fields accepted by `DateTime.add` and `DateTime.subtract`.
+   *
+   * Each field represents the number of units to add or subtract for that part.
+   *
    * @category models
+   * @since 3.6.0
    */
   export interface PartsForMath {
     readonly milliseconds: number
@@ -146,16 +246,24 @@ export declare namespace DateTime {
   }
 
   /**
-   * @since 4.0.0
+   * Object input representing an absolute instant as milliseconds since the Unix
+   * epoch.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Instant {
     readonly epochMilliseconds: number
   }
 
   /**
-   * @since 4.0.0
+   * Object input representing an absolute instant plus a time zone identifier.
+   *
+   * `DateTime.makeZoned` and `DateTime.makeZonedUnsafe` use `timeZoneId` when
+   * no explicit `timeZone` option is supplied.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface InstantWithZone {
     readonly timeZoneId: string
@@ -163,8 +271,13 @@ export declare namespace DateTime {
   }
 
   /**
-   * @since 3.6.0
+   * Shared protocol implemented by all `DateTime` values.
+   *
+   * Provides the `DateTime` type identifier along with pipe and inspection
+   * support.
+   *
    * @category models
+   * @since 3.6.0
    */
   export interface Proto extends Pipeable, Inspectable {
     readonly [TypeId]: typeof TypeId
@@ -172,27 +285,42 @@ export declare namespace DateTime {
 }
 
 /**
- * @since 3.6.0
+ * Represents a time zone used by `DateTime.Zoned`.
+ *
+ * A `TimeZone` is either a fixed offset from UTC or a named IANA time zone.
+ *
  * @category models
+ * @since 3.6.0
  */
 export type TimeZone = TimeZone.Offset | TimeZone.Named
 
 /**
+ * Companion namespace containing the public variant and protocol types for
+ * `TimeZone`.
+ *
  * @since 3.6.0
- * @category models
  */
 export declare namespace TimeZone {
   /**
-   * @since 3.6.0
+   * Shared protocol implemented by all `TimeZone` values.
+   *
+   * Provides the `TimeZone` type identifier and inspection support.
+   *
    * @category models
+   * @since 3.6.0
    */
   export interface Proto extends Inspectable {
     readonly [TimeZoneTypeId]: typeof TimeZoneTypeId
   }
 
   /**
-   * @since 3.6.0
+   * Fixed-offset time zone.
+   *
+   * The `offset` is measured in milliseconds from UTC. Positive offsets are
+   * ahead of UTC, and negative offsets are behind UTC.
+   *
    * @category models
+   * @since 3.6.0
    */
   export interface Offset extends Proto {
     readonly _tag: "Offset"
@@ -200,8 +328,13 @@ export declare namespace TimeZone {
   }
 
   /**
-   * @since 3.6.0
+   * Named IANA time zone.
+   *
+   * The `id` field contains the resolved time zone identifier, such as
+   * `"Europe/London"` or `"America/New_York"`.
+   *
    * @category models
+   * @since 3.6.0
    */
   export interface Named extends Proto {
     readonly _tag: "Named"
@@ -228,7 +361,8 @@ export declare namespace TimeZone {
  *
  * - `"reject"`: Throw an `RangeError` when encountering ambiguous or non-existent times.
  *
- * @example
+ * **Example** (Resolving ambiguous local times)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -268,8 +402,8 @@ export declare namespace TimeZone {
  * // Time after gap: 2025-03-09T07:30:00.000Z (03:30 EDT)
  * ```
  *
- * @since 3.18.0
  * @category models
+ * @since 3.18.0
  */
 export type Disambiguation = "compatible" | "earlier" | "later" | "reject"
 
@@ -278,48 +412,50 @@ export type Disambiguation = "compatible" | "earlier" | "later" | "reject"
 // =============================================================================
 
 /**
- * @since 3.6.0
+ * Checks whether a value is a `DateTime`.
+ *
  * @category guards
+ * @since 3.6.0
  */
 export const isDateTime: (u: unknown) => u is DateTime = Internal.isDateTime
 
 /**
  * Checks if a value is a `TimeZone`.
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isTimeZone: (u: unknown) => u is TimeZone = Internal.isTimeZone
 
 /**
  * Checks if a value is an offset-based `TimeZone`.
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isTimeZoneOffset: (u: unknown) => u is TimeZone.Offset = Internal.isTimeZoneOffset
 
 /**
  * Checks if a value is a named `TimeZone` (IANA time zone).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isTimeZoneNamed: (u: unknown) => u is TimeZone.Named = Internal.isTimeZoneNamed
 
 /**
  * Checks if a `DateTime` is a UTC `DateTime` (no time zone information).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isUtc: (self: DateTime) => self is Utc = Internal.isUtc
 
 /**
  * Checks if a `DateTime` is a zoned `DateTime` (has time zone information).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export const isZoned: (self: DateTime) => self is Zoned = Internal.isZoned
 
@@ -333,7 +469,8 @@ export const isZoned: (self: DateTime) => self is Zoned = Internal.isZoned
  * Two `DateTime` values are considered equivalent if they represent the same
  * point in time, regardless of their time zone.
  *
- * @example
+ * **Example** (Comparing DateTime values for equivalence)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -356,7 +493,8 @@ export const Equivalence: Equ.Equivalence<DateTime> = Internal.Equivalence
  * `DateTime` values are ordered by their epoch milliseconds, so earlier times
  * come before later times regardless of time zone.
  *
- * @example
+ * **Example** (Sorting DateTime values chronologically)
+ *
  * ```ts
  * import { Array, DateTime } from "effect"
  *
@@ -382,7 +520,8 @@ export const Order: order.Order<DateTime> = Internal.Order
  * If the `DateTime` is after the maximum, the maximum is returned.
  * Otherwise, the original `DateTime` is returned.
  *
- * @example
+ * **Example** (Clamping DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -405,7 +544,8 @@ export const clamp: {
    * If the `DateTime` is after the maximum, the maximum is returned.
    * Otherwise, the original `DateTime` is returned.
    *
-   * @example
+   * **Example** (Clamping DateTime values)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -428,7 +568,8 @@ export const clamp: {
    * If the `DateTime` is after the maximum, the maximum is returned.
    * Otherwise, the original `DateTime` is returned.
    *
-   * @example
+   * **Example** (Clamping DateTime values)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -455,7 +596,8 @@ export const clamp: {
  *
  * If the `Date` is invalid, an `IllegalArgumentError` will be thrown.
  *
- * @example
+ * **Example** (Creating DateTime values from Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -466,7 +608,7 @@ export const clamp: {
  * ```
  *
  * @category constructors
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const fromDateUnsafe: (date: Date) => Utc = Internal.fromDateUnsafe
 
@@ -479,21 +621,26 @@ export const fromDateUnsafe: (date: Date) => Utc = Internal.fromDateUnsafe
  * - An object with the parts of a date
  * - A `string` that can be parsed by `Date.parse`
  *
- * @since 3.6.0
- * @category constructors
- * @example
+ * **Example** (Creating DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
  * // from Date
- * DateTime.makeUnsafe(new Date())
+ * const fromDate = DateTime.makeUnsafe(new Date("2024-01-01T12:00:00Z"))
+ * console.log(DateTime.formatIso(fromDate)) // "2024-01-01T12:00:00.000Z"
  *
  * // from parts
- * DateTime.makeUnsafe({ year: 2024 })
+ * const fromParts = DateTime.makeUnsafe({ year: 2024 })
+ * console.log(DateTime.formatIso(fromParts)) // "2024-01-01T00:00:00.000Z"
  *
  * // from string
- * DateTime.makeUnsafe("2024-01-01")
+ * const fromString = DateTime.makeUnsafe("2024-01-01")
+ * console.log(DateTime.formatIso(fromString)) // "2024-01-01T00:00:00.000Z"
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone<A> = Internal.makeUnsafe
 
@@ -511,14 +658,20 @@ export const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.Preser
  * - `later`: Always choose the later of two possible times
  * - `reject`: Throw an error when ambiguous times are encountered
  *
- * @since 3.6.0
- * @category constructors
- * @example
+ * **Example** (Creating zoned DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
- * DateTime.makeZonedUnsafe(new Date(), { timeZone: "Europe/London" })
+ * const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
+ *   timeZone: "Europe/London"
+ * })
+ *
+ * console.log(DateTime.formatIsoZoned(zoned)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const makeZonedUnsafe: (input: DateTime.Input, options?: {
   readonly timeZone?: number | string | TimeZone | undefined
@@ -527,29 +680,41 @@ export const makeZonedUnsafe: (input: DateTime.Input, options?: {
 }) => Zoned = Internal.makeZonedUnsafe
 
 /**
- * Create a `DateTime.Zoned` using `DateTime.make` and a time zone.
+ * Creates a `DateTime.Zoned` from an input and a time zone.
  *
- * The input is treated as UTC and then the time zone is attached, unless
- * `adjustForTimeZone` is set to `true`. In that case, the input is treated as
- * already in the time zone.
+ * By default, the input is interpreted as a UTC instant and the time zone is
+ * attached without changing that instant. When `adjustForTimeZone` is `true`,
+ * the input is interpreted as wall-clock time in the target zone.
  *
- * When `adjustForTimeZone` is true and ambiguous times occur during DST transitions,
- * the `disambiguation` option controls how to resolve the ambiguity:
- * - `compatible` (default): Choose earlier time for repeated times, later for gaps
- * - `earlier`: Always choose the earlier of two possible times
- * - `later`: Always choose the later of two possible times
- * - `reject`: Throw an error when ambiguous times are encountered
+ * When `adjustForTimeZone` is `true`, `disambiguation` controls
+ * daylight-saving gaps and repeated times:
  *
- * If the date time input or time zone is invalid, `None` will be returned.
+ * - `"compatible"` (default): chooses the earlier occurrence for repeated
+ *   times and the later interpretation for gaps
+ * - `"earlier"`: chooses the earlier possible instant
+ * - `"later"`: chooses the later possible instant
+ * - `"reject"`: rejects ambiguous or nonexistent wall-clock times
+ *
+ * Returns `Some` when construction succeeds, or `None` when the input, time
+ * zone, or disambiguation cannot be resolved.
+ *
+ * **Example** (Creating optional zoned DateTime values)
  *
- * @since 3.6.0
- * @category constructors
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
- * DateTime.makeZoned(new Date(), { timeZone: "Europe/London" })
+ * const result = DateTime.makeZoned("2024-06-15T14:30:00Z", {
+ *   timeZone: "Europe/London"
+ * })
+ *
+ * console.log(result._tag) // "Some"
+ * if (result._tag === "Some") {
+ *   console.log(DateTime.formatIsoZoned(result.value)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"
+ * }
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const makeZoned: (
   input: DateTime.Input,
@@ -561,40 +726,54 @@ export const makeZoned: (
 ) => Option.Option<Zoned> = Internal.makeZoned
 
 /**
- * Create a `DateTime` from one of the following:
+ * Creates a `DateTime` from one of the following:
  *
  * - A `DateTime`
- * - A `Date` instance (invalid dates will throw an `IllegalArgumentError`)
- * - The `number` of milliseconds since the Unix epoch
- * - An object with the parts of a date
- * - A `string` that can be parsed by `Date.parse`
+ * - A JavaScript `Date`
+ * - The number of milliseconds since the Unix epoch
+ * - An object with date and time parts
+ * - A string that can be parsed as a date
  *
- * If the input is invalid, `None` will be returned.
+ * Returns `Some` with the constructed `DateTime` when the input is valid, or
+ * `None` when construction would fail, including invalid `Date` instances or
+ * unparseable strings.
+ *
+ * **Example** (Creating optional DateTime values)
  *
- * @since 3.6.0
- * @category constructors
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
  * // from Date
- * DateTime.make(new Date())
+ * const fromDate = DateTime.make(new Date("2024-01-01T12:00:00Z"))
+ * console.log(fromDate._tag) // "Some"
  *
  * // from parts
- * DateTime.make({ year: 2024 })
+ * const fromParts = DateTime.make({ year: 2024 })
+ * console.log(fromParts._tag) // "Some"
  *
  * // from string
- * DateTime.make("2024-01-01")
+ * const fromString = DateTime.make("2024-01-01")
+ * console.log(fromString._tag) // "Some"
+ *
+ * const invalid = DateTime.make("not a date")
+ * console.log(invalid._tag) // "None"
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTime.PreserveZone<A>> = Internal.make
 
 /**
- * Create a `DateTime.Zoned` from a string.
+ * Parses an ISO zoned date-time string into a `DateTime.Zoned`.
  *
- * It uses the format: `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`.
+ * Accepts named-zone strings such as
+ * `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]` and offset-only strings such as
+ * `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`. Returns `None` when the input cannot be
+ * parsed.
+ *
+ * **Example** (Parsing zoned DateTime strings)
  *
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -610,33 +789,36 @@ export const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTim
  * console.log(invalid._tag === "None") // true
  * ```
  *
- * @since 3.6.0
  * @category constructors
+ * @since 3.6.0
  */
 export const makeZonedFromString: (input: string) => Option.Option<Zoned> = Internal.makeZonedFromString
 
 /**
  * Get the current time using the `Clock` service and convert it to a `DateTime`.
  *
- * @since 3.6.0
- * @category constructors
- * @example
+ * **Example** (Getting the current DateTime)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
  * Effect.gen(function*() {
- *   const now = yield* DateTime.now
+ *   const now = yield* DateTime.nowAsDate
+ *   console.log(now instanceof Date) // true
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export const now: Effect.Effect<Utc> = Internal.now
 
 /**
- * Get the current time using the `Clock` service and convert it to a `DateTime`.
+ * Gets the current time from the `Clock` service and returns it as a
+ * JavaScript `Date`.
+ *
+ * **Example** (Getting the current Date)
  *
- * @since 3.6.0
- * @category constructors
- * @example
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -644,6 +826,9 @@ export const now: Effect.Effect<Utc> = Internal.now
  *   const now = yield* DateTime.now
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.14.0
  */
 export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
 
@@ -653,7 +838,8 @@ export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
  * This is a synchronous version of `now` that directly uses `Date.now()`
  * instead of the Effect `Clock` service.
  *
- * @example
+ * **Example** (Getting the current DateTime unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -662,7 +848,7 @@ export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
  * ```
  *
  * @category constructors
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const nowUnsafe: LazyArg<Utc> = Internal.nowUnsafe
 
@@ -673,9 +859,8 @@ export const nowUnsafe: LazyArg<Utc> = Internal.nowUnsafe
 /**
  * For a `DateTime` returns a new `DateTime.Utc`.
  *
- * @since 3.13.0
- * @category time zones
- * @example
+ * **Example** (Converting DateTime values to UTC)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -686,15 +871,17 @@ export const nowUnsafe: LazyArg<Utc> = Internal.nowUnsafe
  * // set as UTC
  * const utc: DateTime.Utc = DateTime.toUtc(now)
  * ```
+ *
+ * @category time zones
+ * @since 3.13.0
  */
 export const toUtc: (self: DateTime) => Utc = Internal.toUtc
 
 /**
  * Set the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting time zones)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -706,14 +893,16 @@ export const toUtc: (self: DateTime) => Utc = Internal.toUtc
  *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const setZone: {
   /**
    * Set the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting time zones)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -725,6 +914,9 @@ export const setZone: {
    *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
    * })
    * ```
+   *
+   * @category time zones
+   * @since 3.6.0
    */
   (
    zone: TimeZone,
@@ -736,9 +928,8 @@ export const setZone: {
   /**
    * Set the time zone of a `DateTime`, returning a new `DateTime.Zoned`.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting time zones)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -750,6 +941,9 @@ export const setZone: {
    *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
    * })
    * ```
+   *
+   * @category time zones
+   * @since 3.6.0
    */
   (
    self: DateTime,
@@ -766,9 +960,8 @@ export const setZone: {
  *
  * The offset is in milliseconds.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting fixed-offset time zones)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -779,6 +972,9 @@ export const setZone: {
  *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const setZoneOffset: {
   /**
@@ -786,9 +982,8 @@ export const setZoneOffset: {
    *
    * The offset is in milliseconds.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting fixed-offset time zones)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -799,6 +994,9 @@ export const setZoneOffset: {
    *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
    * })
    * ```
+   *
+   * @category time zones
+   * @since 3.6.0
    */
   (
    offset: number,
@@ -812,9 +1010,8 @@ export const setZoneOffset: {
    *
    * The offset is in milliseconds.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting fixed-offset time zones)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -825,6 +1022,9 @@ export const setZoneOffset: {
    *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
    * })
    * ```
+   *
+   * @category time zones
+   * @since 3.6.0
    */
   (
    self: DateTime,
@@ -841,7 +1041,8 @@ export const setZoneOffset: {
  *
  * If the time zone is invalid, an `IllegalArgumentError` will be thrown.
  *
- * @example
+ * **Example** (Creating named time zones unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -855,8 +1056,8 @@ export const setZoneOffset: {
  * // DateTime.zoneMakeNamedUnsafe("Invalid/Zone")
  * ```
  *
- * @since 3.6.0
  * @category time zones
+ * @since 4.0.0
  */
 export const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named = Internal.zoneMakeNamedUnsafe
 
@@ -866,7 +1067,8 @@ export const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named = Internal.
  * The offset is specified in milliseconds from UTC. Positive values are
  * ahead of UTC, negative values are behind UTC.
  *
- * @example
+ * **Example** (Creating fixed-offset time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -888,7 +1090,8 @@ export const zoneMakeOffset: (offset: number) => TimeZone.Offset = Internal.zone
  *
  * If the time zone is invalid, `None` will be returned.
  *
- * @example
+ * **Example** (Creating optional named time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -909,7 +1112,8 @@ export const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.Named> =
  *
  * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
  *
- * @example
+ * **Example** (Creating named time zones effectfully)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -932,15 +1136,13 @@ export const zoneMakeNamedEffect: (zoneId: string) => Effect.Effect<TimeZone.Nam
  * This uses the system's configured time zone, which may vary depending
  * on the runtime environment.
  *
- * @example
+ * **Example** (Creating local time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
  * const localZone = DateTime.zoneMakeLocal()
- * const now = DateTime.nowUnsafe()
- * const localTime = DateTime.setZone(now, localZone)
- *
- * console.log(DateTime.formatIsoZoned(localTime))
+ * console.log(DateTime.zoneToString(localZone)) // Output depends on system time zone
  * ```
  *
  * @category time zones
@@ -953,7 +1155,8 @@ export const zoneMakeLocal: () => TimeZone.Named = Internal.zoneMakeLocal
  *
  * Supports both IANA time zone identifiers and offset formats like "+03:00".
  *
- * @example
+ * **Example** (Parsing time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -974,9 +1177,8 @@ export const zoneFromString: (zone: string) => Option.Option<TimeZone> = Interna
 /**
  * Format a `TimeZone` as a string.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Formatting time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -986,6 +1188,9 @@ export const zoneFromString: (zone: string) => Option.Option<TimeZone> = Interna
  * // Outputs "Europe/London"
  * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London"))
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const zoneToString: (self: TimeZone) => string = Internal.zoneToString
 
@@ -993,9 +1198,8 @@ export const zoneToString: (self: TimeZone) => string = Internal.zoneToString
  * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
  * time zone is invalid, `None` will be returned.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting named time zones safely)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1005,15 +1209,17 @@ export const zoneToString: (self: TimeZone) => string = Internal.zoneToString
  *   DateTime.setZoneNamed(now, "Europe/London")
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export const setZoneNamed: {
   /**
    * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
    * time zone is invalid, `None` will be returned.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting named time zones safely)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -1023,6 +1229,9 @@ export const setZoneNamed: {
    *   DateTime.setZoneNamed(now, "Europe/London")
    * })
    * ```
+   *
+   * @category time zones
+   * @since 3.6.0
    */
   (
    zoneId: string,
@@ -1035,9 +1244,8 @@ export const setZoneNamed: {
    * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
    * time zone is invalid, `None` will be returned.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting named time zones safely)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -1047,6 +1255,9 @@ export const setZoneNamed: {
    *   DateTime.setZoneNamed(now, "Europe/London")
    * })
    * ```
+   *
+   * @category time zones
+   * @since 3.6.0
    */
   (
    self: DateTime,
@@ -1062,9 +1273,8 @@ export const setZoneNamed: {
  * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
  * time zone is invalid, an `IllegalArgumentError` will be thrown.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Setting named time zones unsafely)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1074,15 +1284,17 @@ export const setZoneNamed: {
  *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
  * })
  * ```
+ *
+ * @category time zones
+ * @since 4.0.0
  */
 export const setZoneNamedUnsafe: {
   /**
    * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
    * time zone is invalid, an `IllegalArgumentError` will be thrown.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting named time zones unsafely)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -1092,6 +1304,9 @@ export const setZoneNamedUnsafe: {
    *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
    * })
    * ```
+   *
+   * @category time zones
+   * @since 4.0.0
    */
   (
    zoneId: string,
@@ -1104,9 +1319,8 @@ export const setZoneNamedUnsafe: {
    * Set the time zone of a `DateTime` from an IANA time zone identifier. If the
    * time zone is invalid, an `IllegalArgumentError` will be thrown.
    *
-   * @since 3.6.0
-   * @category time zones
-   * @example
+   * **Example** (Setting named time zones unsafely)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -1116,6 +1330,9 @@ export const setZoneNamedUnsafe: {
    *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
    * })
    * ```
+   *
+   * @category time zones
+   * @since 4.0.0
    */
   (
    self: DateTime,
@@ -1139,9 +1356,8 @@ export const setZoneNamedUnsafe: {
  * `other` is *before* `self`, the result will be a negative `Duration`. If they
  * are equal, the result will be a `Duration` of zero.
  *
- * @since 3.6.0
- * @category comparisons
- * @example
+ * **Example** (Measuring distance between DateTime values)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1153,6 +1369,9 @@ export const setZoneNamedUnsafe: {
  *   DateTime.distance(now, other)
  * })
  * ```
+ *
+ * @category comparisons
+ * @since 3.6.0
  */
 export const distance: {
   // =============================================================================
@@ -1167,9 +1386,8 @@ export const distance: {
    * `other` is *before* `self`, the result will be a negative `Duration`. If they
    * are equal, the result will be a `Duration` of zero.
    *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
+   * **Example** (Measuring distance between DateTime values)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -1181,6 +1399,9 @@ export const distance: {
    *   DateTime.distance(now, other)
    * })
    * ```
+   *
+   * @category comparisons
+   * @since 3.6.0
    */
   (other: DateTime): (self: DateTime) => Duration.Duration
   // =============================================================================
@@ -1195,9 +1416,8 @@ export const distance: {
    * `other` is *before* `self`, the result will be a negative `Duration`. If they
    * are equal, the result will be a `Duration` of zero.
    *
-   * @since 3.6.0
-   * @category comparisons
-   * @example
+   * **Example** (Measuring distance between DateTime values)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -1209,6 +1429,9 @@ export const distance: {
    *   DateTime.distance(now, other)
    * })
    * ```
+   *
+   * @category comparisons
+   * @since 3.6.0
    */
   (self: DateTime, other: DateTime): Duration.Duration
 } = Internal.distance
@@ -1216,7 +1439,8 @@ export const distance: {
 /**
  * Returns the earlier of two `DateTime` values.
  *
- * @example
+ * **Example** (Selecting the earlier DateTime)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1234,7 +1458,8 @@ export const min: {
   /**
    * Returns the earlier of two `DateTime` values.
    *
-   * @example
+   * **Example** (Selecting the earlier DateTime)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1252,7 +1477,8 @@ export const min: {
   /**
    * Returns the earlier of two `DateTime` values.
    *
-   * @example
+   * **Example** (Selecting the earlier DateTime)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1272,7 +1498,8 @@ export const min: {
 /**
  * Returns the later of two `DateTime` values.
  *
- * @example
+ * **Example** (Selecting the later DateTime)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1290,7 +1517,8 @@ export const max: {
   /**
    * Returns the later of two `DateTime` values.
    *
-   * @example
+   * **Example** (Selecting the later DateTime)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1308,7 +1536,8 @@ export const max: {
   /**
    * Returns the later of two `DateTime` values.
    *
-   * @example
+   * **Example** (Selecting the later DateTime)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1328,7 +1557,8 @@ export const max: {
 /**
  * Checks if the first `DateTime` is after the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is later)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1340,13 +1570,14 @@ export const max: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isGreaterThan: {
   /**
    * Checks if the first `DateTime` is after the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is later)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1358,13 +1589,14 @@ export const isGreaterThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
    * Checks if the first `DateTime` is after the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is later)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1376,7 +1608,7 @@ export const isGreaterThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isGreaterThan
@@ -1384,7 +1616,8 @@ export const isGreaterThan: {
 /**
  * Checks if the first `DateTime` is after or equal to the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is later or equal)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1398,13 +1631,14 @@ export const isGreaterThan: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isGreaterThanOrEqualTo: {
   /**
    * Checks if the first `DateTime` is after or equal to the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is later or equal)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1418,13 +1652,14 @@ export const isGreaterThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
    * Checks if the first `DateTime` is after or equal to the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is later or equal)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1438,7 +1673,7 @@ export const isGreaterThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isGreaterThanOrEqualTo
@@ -1446,7 +1681,8 @@ export const isGreaterThanOrEqualTo: {
 /**
  * Checks if the first `DateTime` is before the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is earlier)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1458,13 +1694,14 @@ export const isGreaterThanOrEqualTo: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isLessThan: {
   /**
    * Checks if the first `DateTime` is before the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is earlier)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1476,13 +1713,14 @@ export const isLessThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
    * Checks if the first `DateTime` is before the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is earlier)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1494,7 +1732,7 @@ export const isLessThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isLessThan
@@ -1502,7 +1740,8 @@ export const isLessThan: {
 /**
  * Checks if the first `DateTime` is before or equal to the second `DateTime`.
  *
- * @example
+ * **Example** (Checking whether a DateTime is earlier or equal)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1516,13 +1755,14 @@ export const isLessThan: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isLessThanOrEqualTo: {
   /**
    * Checks if the first `DateTime` is before or equal to the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is earlier or equal)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1536,13 +1776,14 @@ export const isLessThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
    * Checks if the first `DateTime` is before or equal to the second `DateTime`.
    *
-   * @example
+   * **Example** (Checking whether a DateTime is earlier or equal)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1556,7 +1797,7 @@ export const isLessThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isLessThanOrEqualTo
@@ -1564,7 +1805,8 @@ export const isLessThanOrEqualTo: {
 /**
  * Checks if a `DateTime` is between two other `DateTime` values (inclusive).
  *
- * @example
+ * **Example** (Checking whether a DateTime is within bounds)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1582,7 +1824,8 @@ export const between: {
   /**
    * Checks if a `DateTime` is between two other `DateTime` values (inclusive).
    *
-   * @example
+   * **Example** (Checking whether a DateTime is within bounds)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1600,7 +1843,8 @@ export const between: {
   /**
    * Checks if a `DateTime` is between two other `DateTime` values (inclusive).
    *
-   * @example
+   * **Example** (Checking whether a DateTime is within bounds)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -1622,7 +1866,8 @@ export const between: {
  *
  * This is an effectful operation that uses the current time from the `Clock` service.
  *
- * @example
+ * **Example** (Checking future DateTime values effectfully)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1643,7 +1888,8 @@ export const isFuture: (self: DateTime) => Effect.Effect<boolean> = Internal.isF
  *
  * This is a synchronous version that uses `Date.now()` directly.
  *
- * @example
+ * **Example** (Checking future DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1655,7 +1901,7 @@ export const isFuture: (self: DateTime) => Effect.Effect<boolean> = Internal.isF
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isFutureUnsafe: (self: DateTime) => boolean = Internal.isFutureUnsafe
 
@@ -1664,7 +1910,8 @@ export const isFutureUnsafe: (self: DateTime) => boolean = Internal.isFutureUnsa
  *
  * This is an effectful operation that uses the current time from the `Clock` service.
  *
- * @example
+ * **Example** (Checking past DateTime values effectfully)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -1685,7 +1932,8 @@ export const isPast: (self: DateTime) => Effect.Effect<boolean> = Internal.isPas
  *
  * This is a synchronous version that uses `Date.now()` directly.
  *
- * @example
+ * **Example** (Checking past DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1697,7 +1945,7 @@ export const isPast: (self: DateTime) => Effect.Effect<boolean> = Internal.isPas
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
 
@@ -1710,7 +1958,8 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
  *
  * This always returns the UTC representation, ignoring any time zone information.
  *
- * @example
+ * **Example** (Converting DateTime values to UTC Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1722,7 +1971,7 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
  * console.log(utcDate.toISOString()) // "2024-01-01T12:00:00.000Z"
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
@@ -1733,7 +1982,8 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
  * For `DateTime.Zoned`, this adjusts for the time zone before converting.
  * For `DateTime.Utc`, this is equivalent to `toDateUtc`.
  *
- * @example
+ * **Example** (Converting DateTime values to Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1746,7 +1996,7 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
  * console.log(DateTime.toDate(zoned).toISOString())
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const toDate: (self: DateTime) => Date = Internal.toDate
@@ -1757,7 +2007,8 @@ export const toDate: (self: DateTime) => Date = Internal.toDate
  * Returns the offset from UTC in milliseconds. Positive values indicate
  * time zones ahead of UTC, negative values indicate time zones behind UTC.
  *
- * @example
+ * **Example** (Reading zoned offsets)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1769,7 +2020,7 @@ export const toDate: (self: DateTime) => Date = Internal.toDate
  * console.log(offset) // 0 (London is UTC+0 in winter)
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
@@ -1779,7 +2030,8 @@ export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
  *
  * The offset is formatted as "±HH:MM".
  *
- * @example
+ * **Example** (Formatting zoned offsets)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1791,7 +2043,7 @@ export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
  * console.log(offsetString) // "+03:00"
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
@@ -1801,7 +2053,8 @@ export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
  *
  * This returns the UTC timestamp regardless of any time zone information.
  *
- * @example
+ * **Example** (Reading epoch milliseconds)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1809,10 +2062,9 @@ export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
  * const epochMillis = DateTime.toEpochMillis(dt)
  *
  * console.log(epochMillis) // 1704067200000
- * console.log(new Date(epochMillis).toISOString()) // "2024-01-01T00:00:00.000Z"
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const toEpochMillis: (self: DateTime) => number = Internal.toEpochMillis
@@ -1821,9 +2073,8 @@ export const toEpochMillis: (self: DateTime) => number = Internal.toEpochMillis
  * Remove the time aspect of a `DateTime`, first adjusting for the time
  * zone. It will return a `DateTime.Utc` only containing the date.
  *
- * @since 3.6.0
- * @category conversions
- * @example
+ * **Example** (Removing time components)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1836,6 +2087,9 @@ export const toEpochMillis: (self: DateTime) => number = Internal.toEpochMillis
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category converting
+ * @since 3.6.0
  */
 export const removeTime: (self: DateTime) => Utc = Internal.removeTime
 
@@ -1848,7 +2102,8 @@ export const removeTime: (self: DateTime) => Utc = Internal.removeTime
  *
  * The parts will be time zone adjusted if the `DateTime` is zoned.
  *
- * @example
+ * **Example** (Reading DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1878,7 +2133,8 @@ export const toParts: (self: DateTime) => DateTime.PartsWithWeekday = Internal.t
  *
  * The parts will always be in UTC, ignoring any time zone information.
  *
- * @example
+ * **Example** (Reading UTC DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1901,17 +2157,18 @@ export const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday = Interna
  *
  * The part will be in the UTC time zone.
  *
- * @since 3.6.0
- * @category parts
- * @example
+ * **Example** (Reading UTC DateTime parts by key)
+ *
  * ```ts
  * import { DateTime } from "effect"
- * import * as assert from "node:assert"
  *
- * const now = DateTime.makeUnsafe({ year: 2024 })
- * const year = DateTime.getPartUtc(now, "year")
- * assert.strictEqual(year, 2024)
+ * const dateTime = DateTime.makeUnsafe({ year: 2024 })
+ * const year = DateTime.getPartUtc(dateTime, "year")
+ * console.log(year) // 2024
  * ```
+ *
+ * @category parts
+ * @since 3.6.0
  */
 export const getPartUtc: {
   /**
@@ -1919,17 +2176,18 @@ export const getPartUtc: {
    *
    * The part will be in the UTC time zone.
    *
-   * @since 3.6.0
-   * @category parts
-   * @example
+   * **Example** (Reading UTC DateTime parts by key)
+   *
    * ```ts
    * import { DateTime } from "effect"
-   * import * as assert from "node:assert"
    *
-   * const now = DateTime.makeUnsafe({ year: 2024 })
-   * const year = DateTime.getPartUtc(now, "year")
-   * assert.strictEqual(year, 2024)
+   * const dateTime = DateTime.makeUnsafe({ year: 2024 })
+   * const year = DateTime.getPartUtc(dateTime, "year")
+   * console.log(year) // 2024
    * ```
+   *
+   * @category parts
+   * @since 3.6.0
    */
   (part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
   /**
@@ -1937,17 +2195,18 @@ export const getPartUtc: {
    *
    * The part will be in the UTC time zone.
    *
-   * @since 3.6.0
-   * @category parts
-   * @example
+   * **Example** (Reading UTC DateTime parts by key)
+   *
    * ```ts
    * import { DateTime } from "effect"
-   * import * as assert from "node:assert"
    *
-   * const now = DateTime.makeUnsafe({ year: 2024 })
-   * const year = DateTime.getPartUtc(now, "year")
-   * assert.strictEqual(year, 2024)
+   * const dateTime = DateTime.makeUnsafe({ year: 2024 })
+   * const year = DateTime.getPartUtc(dateTime, "year")
+   * console.log(year) // 2024
    * ```
+   *
+   * @category parts
+   * @since 3.6.0
    */
   (self: DateTime, part: keyof DateTime.PartsWithWeekday): number
 } = Internal.getPartUtc
@@ -1957,19 +2216,20 @@ export const getPartUtc: {
  *
  * The part will be time zone adjusted.
  *
- * @since 3.6.0
- * @category parts
- * @example
+ * **Example** (Reading DateTime parts by key)
+ *
  * ```ts
  * import { DateTime } from "effect"
- * import * as assert from "node:assert"
  *
- * const now = DateTime.makeZonedUnsafe({ year: 2024 }, {
+ * const dateTime = DateTime.makeZonedUnsafe({ year: 2024 }, {
  *   timeZone: "Europe/London"
  * })
- * const year = DateTime.getPart(now, "year")
- * assert.strictEqual(year, 2024)
+ * const year = DateTime.getPart(dateTime, "year")
+ * console.log(year) // 2024
  * ```
+ *
+ * @category parts
+ * @since 3.6.0
  */
 export const getPart: {
   /**
@@ -1977,19 +2237,20 @@ export const getPart: {
    *
    * The part will be time zone adjusted.
    *
-   * @since 3.6.0
-   * @category parts
-   * @example
+   * **Example** (Reading DateTime parts by key)
+   *
    * ```ts
    * import { DateTime } from "effect"
-   * import * as assert from "node:assert"
    *
-   * const now = DateTime.makeZonedUnsafe({ year: 2024 }, {
+   * const dateTime = DateTime.makeZonedUnsafe({ year: 2024 }, {
    *   timeZone: "Europe/London"
    * })
-   * const year = DateTime.getPart(now, "year")
-   * assert.strictEqual(year, 2024)
+   * const year = DateTime.getPart(dateTime, "year")
+   * console.log(year) // 2024
    * ```
+   *
+   * @category parts
+   * @since 3.6.0
    */
   (part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
   /**
@@ -1997,19 +2258,20 @@ export const getPart: {
    *
    * The part will be time zone adjusted.
    *
-   * @since 3.6.0
-   * @category parts
-   * @example
+   * **Example** (Reading DateTime parts by key)
+   *
    * ```ts
    * import { DateTime } from "effect"
-   * import * as assert from "node:assert"
    *
-   * const now = DateTime.makeZonedUnsafe({ year: 2024 }, {
+   * const dateTime = DateTime.makeZonedUnsafe({ year: 2024 }, {
    *   timeZone: "Europe/London"
    * })
-   * const year = DateTime.getPart(now, "year")
-   * assert.strictEqual(year, 2024)
+   * const year = DateTime.getPart(dateTime, "year")
+   * console.log(year) // 2024
    * ```
+   *
+   * @category parts
+   * @since 3.6.0
    */
   (self: DateTime, part: keyof DateTime.PartsWithWeekday): number
 } = Internal.getPart
@@ -2019,7 +2281,8 @@ export const getPart: {
  *
  * The date will be time zone adjusted for `DateTime.Zoned`.
  *
- * @example
+ * **Example** (Updating DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2042,7 +2305,8 @@ export const setParts: {
    *
    * The date will be time zone adjusted for `DateTime.Zoned`.
    *
-   * @example
+   * **Example** (Updating DateTime parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2065,7 +2329,8 @@ export const setParts: {
    *
    * The date will be time zone adjusted for `DateTime.Zoned`.
    *
-   * @example
+   * **Example** (Updating DateTime parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2090,7 +2355,8 @@ export const setParts: {
  *
  * The parts are always interpreted as UTC, ignoring any time zone information.
  *
- * @example
+ * **Example** (Updating UTC DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2112,7 +2378,8 @@ export const setPartsUtc: {
    *
    * The parts are always interpreted as UTC, ignoring any time zone information.
    *
-   * @example
+   * **Example** (Updating UTC DateTime parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2134,7 +2401,8 @@ export const setPartsUtc: {
    *
    * The parts are always interpreted as UTC, ignoring any time zone information.
    *
-   * @example
+   * **Example** (Updating UTC DateTime parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2158,7 +2426,15 @@ export const setPartsUtc: {
 // =============================================================================
 
 /**
- * @example
+ * Context service that supplies the ambient `TimeZone` for APIs that work in
+ * the current zone, such as `DateTime.setZoneCurrent` and
+ * `DateTime.nowInCurrentZone`.
+ *
+ * Provide it with `DateTime.withCurrentZone`, one of the `withCurrentZone*`
+ * helpers, or one of the `layerCurrentZone*` layers.
+ *
+ * **Example** (Accessing the current time zone service)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -2173,8 +2449,8 @@ export const setPartsUtc: {
  * Effect.provide(program, layer)
  * ```
  *
- * @since 3.11.0
  * @category current time zone
+ * @since 3.11.0
  */
 export class CurrentTimeZone extends Context.Service<CurrentTimeZone, TimeZone>()(
   "effect/DateTime/CurrentTimeZone"
@@ -2184,9 +2460,8 @@ export class CurrentTimeZone extends Context.Service<CurrentTimeZone, TimeZone>(
  * Set the time zone of a `DateTime` to the current time zone, which is
  * determined by the `CurrentTimeZone` service.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Setting the current time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -2197,6 +2472,9 @@ export class CurrentTimeZone extends Context.Service<CurrentTimeZone, TimeZone>(
  *   const zoned = yield* DateTime.setZoneCurrent(now)
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const setZoneCurrent = (self: DateTime): Effect.Effect<Zoned, never, CurrentTimeZone> =>
   Effect.map(CurrentTimeZone, (zone) => setZone(self, zone))
@@ -2204,9 +2482,8 @@ export const setZoneCurrent = (self: DateTime): Effect.Effect<Zoned, never, Curr
 /**
  * Provide the `CurrentTimeZone` to an effect.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing the current time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -2216,14 +2493,16 @@ export const setZoneCurrent = (self: DateTime): Effect.Effect<Zoned, never, Curr
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZone(zone))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZone: {
   /**
    * Provide the `CurrentTimeZone` to an effect.
    *
-   * @since 3.6.0
-   * @category current time zone
-   * @example
+   * **Example** (Providing the current time zone)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -2233,14 +2512,16 @@ export const withCurrentZone: {
    *   const now = yield* DateTime.nowInCurrentZone
    * }).pipe(DateTime.withCurrentZone(zone))
    * ```
+   *
+   * @category current time zone
+   * @since 3.6.0
    */
   (value: TimeZone): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
   /**
    * Provide the `CurrentTimeZone` to an effect.
    *
-   * @since 3.6.0
-   * @category current time zone
-   * @example
+   * **Example** (Providing the current time zone)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -2250,6 +2531,9 @@ export const withCurrentZone: {
    *   const now = yield* DateTime.nowInCurrentZone
    * }).pipe(DateTime.withCurrentZone(zone))
    * ```
+   *
+   * @category current time zone
+   * @since 3.6.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, value: TimeZone): Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
 } = provideService(CurrentTimeZone)
@@ -2258,9 +2542,8 @@ export const withCurrentZone: {
  * Provide the `CurrentTimeZone` to an effect, using the system's local time
  * zone.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing the local time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -2269,6 +2552,9 @@ export const withCurrentZone: {
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneLocal)
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZoneLocal = <A, E, R>(
   effect: Effect.Effect<A, E, R>
@@ -2278,33 +2564,37 @@ export const withCurrentZoneLocal = <A, E, R>(
 /**
  * Provide the `CurrentTimeZone` to an effect, using a offset.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing a fixed-offset time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
  * Effect.gen(function*() {
- *   // will use the system's local time zone
- *   const now = yield* DateTime.nowInCurrentZone
+ *   const zone = yield* DateTime.CurrentTimeZone
+ *   console.log(DateTime.zoneToString(zone)) // "+03:00"
  * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZoneOffset: {
   /**
    * Provide the `CurrentTimeZone` to an effect, using a offset.
    *
-   * @since 3.6.0
-   * @category current time zone
-   * @example
+   * **Example** (Providing a fixed-offset time zone)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
    * Effect.gen(function*() {
-   *   // will use the system's local time zone
-   *   const now = yield* DateTime.nowInCurrentZone
+   *   const zone = yield* DateTime.CurrentTimeZone
+   *   console.log(DateTime.zoneToString(zone)) // "+03:00"
    * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
    * ```
+   *
+   * @category current time zone
+   * @since 3.6.0
    */
   (offset: number): <A, E, R>(
     effect: Effect.Effect<A, E, R>
@@ -2312,17 +2602,19 @@ export const withCurrentZoneOffset: {
   /**
    * Provide the `CurrentTimeZone` to an effect, using a offset.
    *
-   * @since 3.6.0
-   * @category current time zone
-   * @example
+   * **Example** (Providing a fixed-offset time zone)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
    * Effect.gen(function*() {
-   *   // will use the system's local time zone
-   *   const now = yield* DateTime.nowInCurrentZone
+   *   const zone = yield* DateTime.CurrentTimeZone
+   *   console.log(DateTime.zoneToString(zone)) // "+03:00"
    * }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
    * ```
+   *
+   * @category current time zone
+   * @since 3.6.0
    */
   <A, E, R>(effect: Effect.Effect<A, E, R>, offset: number): Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>
 } = dual(
@@ -2337,9 +2629,8 @@ export const withCurrentZoneOffset: {
  *
  * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Providing a named time zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -2348,6 +2639,9 @@ export const withCurrentZoneOffset: {
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const withCurrentZoneNamed: {
   /**
@@ -2356,9 +2650,8 @@ export const withCurrentZoneNamed: {
    *
    * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
    *
-   * @since 3.6.0
-   * @category current time zone
-   * @example
+   * **Example** (Providing a named time zone)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -2367,6 +2660,9 @@ export const withCurrentZoneNamed: {
    *   const now = yield* DateTime.nowInCurrentZone
    * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
    * ```
+   *
+   * @category current time zone
+   * @since 3.6.0
    */
   (zone: string): <A, E, R>(
     effect: Effect.Effect<A, E, R>
@@ -2377,9 +2673,8 @@ export const withCurrentZoneNamed: {
    *
    * If the time zone is invalid, it will fail with an `IllegalArgumentError`.
    *
-   * @since 3.6.0
-   * @category current time zone
-   * @example
+   * **Example** (Providing a named time zone)
+   *
    * ```ts
    * import { DateTime, Effect } from "effect"
    *
@@ -2388,6 +2683,9 @@ export const withCurrentZoneNamed: {
    *   const now = yield* DateTime.nowInCurrentZone
    * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
    * ```
+   *
+   * @category current time zone
+   * @since 3.6.0
    */
   <A, E, R>(effect: Effect.Effect<A, E, R>, zone: string): Effect.Effect<A, E | IllegalArgumentError, Exclude<R, CurrentTimeZone>>
 } = dual(
@@ -2402,9 +2700,8 @@ export const withCurrentZoneNamed: {
 /**
  * Get the current time as a `DateTime.Zoned`, using the `CurrentTimeZone`.
  *
- * @since 3.6.0
- * @category current time zone
- * @example
+ * **Example** (Getting the current time in the current zone)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -2413,6 +2710,9 @@ export const withCurrentZoneNamed: {
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone> = Effect.flatMap(now, setZoneCurrent)
 
@@ -2428,7 +2728,8 @@ export const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone> = Ef
  *
  * Supports `disambiguation` when the new wall clock time is ambiguous.
  *
- * @example
+ * **Example** (Mutating DateTime values with Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2442,8 +2743,8 @@ export const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone> = Ef
  * console.log(DateTime.formatIso(modified)) // "2024-01-01T15:30:00.000Z"
  * ```
  *
- * @since 3.6.0
  * @category mapping
+ * @since 3.6.0
  */
 export const mutate: {
   // =============================================================================
@@ -2458,7 +2759,8 @@ export const mutate: {
    *
    * Supports `disambiguation` when the new wall clock time is ambiguous.
    *
-   * @example
+   * **Example** (Mutating DateTime values with Dates)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2472,8 +2774,8 @@ export const mutate: {
    * console.log(DateTime.formatIso(modified)) // "2024-01-01T15:30:00.000Z"
    * ```
    *
-   * @since 3.6.0
    * @category mapping
+   * @since 3.6.0
    */
   (
    f: (date: Date) => void,
@@ -2493,7 +2795,8 @@ export const mutate: {
    *
    * Supports `disambiguation` when the new wall clock time is ambiguous.
    *
-   * @example
+   * **Example** (Mutating DateTime values with Dates)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2507,8 +2810,8 @@ export const mutate: {
    * console.log(DateTime.formatIso(modified)) // "2024-01-01T15:30:00.000Z"
    * ```
    *
-   * @since 3.6.0
    * @category mapping
+   * @since 3.6.0
    */
   <A extends DateTime>(
    self: A,
@@ -2522,7 +2825,8 @@ export const mutate: {
 /**
  * Modify a `DateTime` by applying a function to a cloned UTC `Date` instance.
  *
- * @example
+ * **Example** (Mutating DateTime values with UTC Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2537,14 +2841,15 @@ export const mutate: {
  * console.log(DateTime.formatIso(modified)) // "2024-01-01T18:00:00.000Z"
  * ```
  *
- * @since 3.6.0
  * @category mapping
+ * @since 3.6.0
  */
 export const mutateUtc: {
   /**
    * Modify a `DateTime` by applying a function to a cloned UTC `Date` instance.
    *
-   * @example
+   * **Example** (Mutating DateTime values with UTC Dates)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2559,14 +2864,15 @@ export const mutateUtc: {
    * console.log(DateTime.formatIso(modified)) // "2024-01-01T18:00:00.000Z"
    * ```
    *
-   * @since 3.6.0
    * @category mapping
+   * @since 3.6.0
    */
   (f: (date: Date) => void): <A extends DateTime>(self: A) => A
   /**
    * Modify a `DateTime` by applying a function to a cloned UTC `Date` instance.
    *
-   * @example
+   * **Example** (Mutating DateTime values with UTC Dates)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2581,8 +2887,8 @@ export const mutateUtc: {
    * console.log(DateTime.formatIso(modified)) // "2024-01-01T18:00:00.000Z"
    * ```
    *
-   * @since 3.6.0
    * @category mapping
+   * @since 3.6.0
    */
   <A extends DateTime>(self: A, f: (date: Date) => void): A
 } = Internal.mutateUtc
@@ -2591,9 +2897,8 @@ export const mutateUtc: {
  * Transform a `DateTime` by applying a function to the number of milliseconds
  * since the Unix epoch.
  *
- * @since 3.6.0
- * @category mapping
- * @example
+ * **Example** (Mapping epoch milliseconds)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2602,15 +2907,17 @@ export const mutateUtc: {
  *   DateTime.mapEpochMillis((millis) => millis + 10)
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export const mapEpochMillis: {
   /**
    * Transform a `DateTime` by applying a function to the number of milliseconds
    * since the Unix epoch.
    *
-   * @since 3.6.0
-   * @category mapping
-   * @example
+   * **Example** (Mapping epoch milliseconds)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2619,15 +2926,17 @@ export const mapEpochMillis: {
    *   DateTime.mapEpochMillis((millis) => millis + 10)
    * )
    * ```
+   *
+   * @category mapping
+   * @since 3.6.0
    */
   (f: (millis: number) => number): <A extends DateTime>(self: A) => A
   /**
    * Transform a `DateTime` by applying a function to the number of milliseconds
    * since the Unix epoch.
    *
-   * @since 3.6.0
-   * @category mapping
-   * @example
+   * **Example** (Mapping epoch milliseconds)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2636,17 +2945,22 @@ export const mapEpochMillis: {
    *   DateTime.mapEpochMillis((millis) => millis + 10)
    * )
    * ```
+   *
+   * @category mapping
+   * @since 3.6.0
    */
   <A extends DateTime>(self: A, f: (millis: number) => number): A
 } = Internal.mapEpochMillis
 
 /**
- * Using the time zone adjusted `Date`, apply a function to the `Date` and
- * return the result.
+ * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+ * instant and returns the function's result.
+ *
+ * This ignores any associated time zone. Use `DateTime.withDate` when the
+ * callback should receive the time-zone-adjusted wall-clock date.
+ *
+ * **Example** (Using time zone adjusted Dates)
  *
- * @since 3.6.0
- * @category mapping
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2655,15 +2969,20 @@ export const mapEpochMillis: {
  *   DateTime.withDate((date) => date.getTime())
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export const withDate: {
   /**
-   * Using the time zone adjusted `Date`, apply a function to the `Date` and
-   * return the result.
+   * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+   * instant and returns the function's result.
+   *
+   * This ignores any associated time zone. Use `DateTime.withDate` when the
+   * callback should receive the time-zone-adjusted wall-clock date.
+   *
+   * **Example** (Using time zone adjusted Dates)
    *
-   * @since 3.6.0
-   * @category mapping
-   * @example
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2672,15 +2991,20 @@ export const withDate: {
    *   DateTime.withDate((date) => date.getTime())
    * )
    * ```
+   *
+   * @category mapping
+   * @since 3.6.0
    */
   <A>(f: (date: Date) => A): (self: DateTime) => A
   /**
-   * Using the time zone adjusted `Date`, apply a function to the `Date` and
-   * return the result.
+   * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+   * instant and returns the function's result.
+   *
+   * This ignores any associated time zone. Use `DateTime.withDate` when the
+   * callback should receive the time-zone-adjusted wall-clock date.
+   *
+   * **Example** (Using time zone adjusted Dates)
    *
-   * @since 3.6.0
-   * @category mapping
-   * @example
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2689,17 +3013,22 @@ export const withDate: {
    *   DateTime.withDate((date) => date.getTime())
    * )
    * ```
+   *
+   * @category mapping
+   * @since 3.6.0
    */
   <A>(self: DateTime, f: (date: Date) => A): A
 } = Internal.withDate
 
 /**
- * Using the time zone adjusted `Date`, apply a function to the `Date` and
- * return the result.
+ * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+ * instant and returns the function's result.
+ *
+ * This ignores any associated time zone. Use `DateTime.withDate` when the
+ * callback should receive the time-zone-adjusted wall-clock date.
+ *
+ * **Example** (Using UTC Dates)
  *
- * @since 3.6.0
- * @category mapping
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2708,15 +3037,20 @@ export const withDate: {
  *   DateTime.withDateUtc((date) => date.getTime())
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export const withDateUtc: {
   /**
-   * Using the time zone adjusted `Date`, apply a function to the `Date` and
-   * return the result.
+   * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+   * instant and returns the function's result.
+   *
+   * This ignores any associated time zone. Use `DateTime.withDate` when the
+   * callback should receive the time-zone-adjusted wall-clock date.
+   *
+   * **Example** (Using UTC Dates)
    *
-   * @since 3.6.0
-   * @category mapping
-   * @example
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2725,15 +3059,20 @@ export const withDateUtc: {
    *   DateTime.withDateUtc((date) => date.getTime())
    * )
    * ```
+   *
+   * @category mapping
+   * @since 3.6.0
    */
   <A>(f: (date: Date) => A): (self: DateTime) => A
   /**
-   * Using the time zone adjusted `Date`, apply a function to the `Date` and
-   * return the result.
+   * Applies a function to a JavaScript `Date` representing the `DateTime`'s UTC
+   * instant and returns the function's result.
+   *
+   * This ignores any associated time zone. Use `DateTime.withDate` when the
+   * callback should receive the time-zone-adjusted wall-clock date.
+   *
+   * **Example** (Using UTC Dates)
    *
-   * @since 3.6.0
-   * @category mapping
-   * @example
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2742,6 +3081,9 @@ export const withDateUtc: {
    *   DateTime.withDateUtc((date) => date.getTime())
    * )
    * ```
+   *
+   * @category mapping
+   * @since 3.6.0
    */
   <A>(self: DateTime, f: (date: Date) => A): A
 } = Internal.withDateUtc
@@ -2749,12 +3091,15 @@ export const withDateUtc: {
 /**
  * Pattern match on a `DateTime` to handle `Utc` and `Zoned` cases differently.
  *
- * @example
+ * **Example** (Pattern matching DateTime variants)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
- * const dt1 = DateTime.nowUnsafe() // Utc
- * const dt2 = DateTime.makeZonedUnsafe(new Date(), { timeZone: "Europe/London" }) // Zoned
+ * const dt1 = DateTime.makeUnsafe("2024-01-01T12:00:00Z") // Utc
+ * const dt2 = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
+ *   timeZone: "Europe/London"
+ * }) // Zoned
  *
  * const result1 = DateTime.match(dt1, {
  *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
@@ -2765,6 +3110,9 @@ export const withDateUtc: {
  *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
  *   onZoned: (zoned) => `Zoned: ${DateTime.formatIsoZoned(zoned)}`
  * })
+ *
+ * console.log(result1) // "UTC: 2024-01-01T12:00:00.000Z"
+ * console.log(result2) // "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
  * ```
  *
  * @category mapping
@@ -2774,12 +3122,15 @@ export const match: {
   /**
    * Pattern match on a `DateTime` to handle `Utc` and `Zoned` cases differently.
    *
-   * @example
+   * **Example** (Pattern matching DateTime variants)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
-   * const dt1 = DateTime.nowUnsafe() // Utc
-   * const dt2 = DateTime.makeZonedUnsafe(new Date(), { timeZone: "Europe/London" }) // Zoned
+   * const dt1 = DateTime.makeUnsafe("2024-01-01T12:00:00Z") // Utc
+   * const dt2 = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
+   *   timeZone: "Europe/London"
+   * }) // Zoned
    *
    * const result1 = DateTime.match(dt1, {
    *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
@@ -2790,6 +3141,9 @@ export const match: {
    *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
    *   onZoned: (zoned) => `Zoned: ${DateTime.formatIsoZoned(zoned)}`
    * })
+   *
+   * console.log(result1) // "UTC: 2024-01-01T12:00:00.000Z"
+   * console.log(result2) // "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
    * ```
    *
    * @category mapping
@@ -2804,12 +3158,15 @@ export const match: {
   /**
    * Pattern match on a `DateTime` to handle `Utc` and `Zoned` cases differently.
    *
-   * @example
+   * **Example** (Pattern matching DateTime variants)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
-   * const dt1 = DateTime.nowUnsafe() // Utc
-   * const dt2 = DateTime.makeZonedUnsafe(new Date(), { timeZone: "Europe/London" }) // Zoned
+   * const dt1 = DateTime.makeUnsafe("2024-01-01T12:00:00Z") // Utc
+   * const dt2 = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
+   *   timeZone: "Europe/London"
+   * }) // Zoned
    *
    * const result1 = DateTime.match(dt1, {
    *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
@@ -2820,6 +3177,9 @@ export const match: {
    *   onUtc: (utc) => `UTC: ${DateTime.formatIso(utc)}`,
    *   onZoned: (zoned) => `Zoned: ${DateTime.formatIsoZoned(zoned)}`
    * })
+   *
+   * console.log(result1) // "UTC: 2024-01-01T12:00:00.000Z"
+   * console.log(result2) // "Zoned: 2024-06-15T15:30:00.000+01:00[Europe/London]"
    * ```
    *
    * @category mapping
@@ -2841,9 +3201,8 @@ export const match: {
 /**
  * Add the given `Duration` to a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Adding durations)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2852,6 +3211,9 @@ export const match: {
  *   DateTime.addDuration("5 minutes")
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const addDuration: {
   // =============================================================================
@@ -2861,9 +3223,8 @@ export const addDuration: {
   /**
    * Add the given `Duration` to a `DateTime`.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Adding durations)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2872,6 +3233,9 @@ export const addDuration: {
    *   DateTime.addDuration("5 minutes")
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   (duration: Duration.Input): <A extends DateTime>(self: A) => A
   // =============================================================================
@@ -2881,9 +3245,8 @@ export const addDuration: {
   /**
    * Add the given `Duration` to a `DateTime`.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Adding durations)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2892,6 +3255,9 @@ export const addDuration: {
    *   DateTime.addDuration("5 minutes")
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   <A extends DateTime>(self: A, duration: Duration.Input): A
 } = Internal.addDuration
@@ -2899,9 +3265,8 @@ export const addDuration: {
 /**
  * Subtract the given `Duration` from a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Subtracting durations)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2910,14 +3275,16 @@ export const addDuration: {
  *   DateTime.subtractDuration("5 minutes")
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const subtractDuration: {
   /**
    * Subtract the given `Duration` from a `DateTime`.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Subtracting durations)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2926,14 +3293,16 @@ export const subtractDuration: {
    *   DateTime.subtractDuration("5 minutes")
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   (duration: Duration.Input): <A extends DateTime>(self: A) => A
   /**
    * Subtract the given `Duration` from a `DateTime`.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Subtracting durations)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2942,6 +3311,9 @@ export const subtractDuration: {
    *   DateTime.subtractDuration("5 minutes")
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   <A extends DateTime>(self: A, duration: Duration.Input): A
 } = Internal.subtractDuration
@@ -2952,9 +3324,8 @@ export const subtractDuration: {
  * The time zone is taken into account when adding days, weeks, months, and
  * years.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Adding date and time parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2963,6 +3334,9 @@ export const subtractDuration: {
  *   DateTime.add({ minutes: 5 })
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const add: {
   /**
@@ -2971,9 +3345,8 @@ export const add: {
    * The time zone is taken into account when adding days, weeks, months, and
    * years.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Adding date and time parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -2982,6 +3355,9 @@ export const add: {
    *   DateTime.add({ minutes: 5 })
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A
   /**
@@ -2990,9 +3366,8 @@ export const add: {
    * The time zone is taken into account when adding days, weeks, months, and
    * years.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Adding date and time parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3001,6 +3376,9 @@ export const add: {
    *   DateTime.add({ minutes: 5 })
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): A
 } = Internal.add
@@ -3008,9 +3386,8 @@ export const add: {
 /**
  * Subtract the given `amount` of `unit`'s from a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Subtracting date and time parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3019,14 +3396,16 @@ export const add: {
  *   DateTime.subtract({ minutes: 5 })
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const subtract: {
   /**
    * Subtract the given `amount` of `unit`'s from a `DateTime`.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Subtracting date and time parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3035,14 +3414,16 @@ export const subtract: {
    *   DateTime.subtract({ minutes: 5 })
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A
   /**
    * Subtract the given `amount` of `unit`'s from a `DateTime`.
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Subtracting date and time parts)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3051,6 +3432,9 @@ export const subtract: {
    *   DateTime.subtract({ minutes: 5 })
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): A
 } = Internal.subtract
@@ -3061,9 +3445,8 @@ export const subtract: {
  * If the part is `week`, the `weekStartsOn` option can be used to specify the
  * day of the week that the week starts on. The default is 0 (Sunday).
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Rounding down DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3073,6 +3456,9 @@ export const subtract: {
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const startOf: {
   /**
@@ -3081,9 +3467,8 @@ export const startOf: {
    * If the part is `week`, the `weekStartsOn` option can be used to specify the
    * day of the week that the week starts on. The default is 0 (Sunday).
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Rounding down DateTime values)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3093,6 +3478,9 @@ export const startOf: {
    *   DateTime.formatIso
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   (
    part: DateTime.UnitSingular,
@@ -3104,9 +3492,8 @@ export const startOf: {
    * If the part is `week`, the `weekStartsOn` option can be used to specify the
    * day of the week that the week starts on. The default is 0 (Sunday).
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Rounding down DateTime values)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3116,6 +3503,9 @@ export const startOf: {
    *   DateTime.formatIso
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   <A extends DateTime>(
    self: A,
@@ -3130,9 +3520,8 @@ export const startOf: {
  * If the part is `week`, the `weekStartsOn` option can be used to specify the
  * day of the week that the week starts on. The default is 0 (Sunday).
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Rounding up DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3142,6 +3531,9 @@ export const startOf: {
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const endOf: {
   /**
@@ -3150,9 +3542,8 @@ export const endOf: {
    * If the part is `week`, the `weekStartsOn` option can be used to specify the
    * day of the week that the week starts on. The default is 0 (Sunday).
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Rounding up DateTime values)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3162,6 +3553,9 @@ export const endOf: {
    *   DateTime.formatIso
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   (
    part: DateTime.UnitSingular,
@@ -3173,9 +3567,8 @@ export const endOf: {
    * If the part is `week`, the `weekStartsOn` option can be used to specify the
    * day of the week that the week starts on. The default is 0 (Sunday).
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Rounding up DateTime values)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3185,6 +3578,9 @@ export const endOf: {
    *   DateTime.formatIso
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   <A extends DateTime>(
    self: A,
@@ -3199,9 +3595,8 @@ export const endOf: {
  * If the part is `week`, the `weekStartsOn` option can be used to specify the
  * day of the week that the week starts on. The default is 0 (Sunday).
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Rounding DateTime values to nearest units)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3211,6 +3606,9 @@ export const endOf: {
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export const nearest: {
   /**
@@ -3219,9 +3617,8 @@ export const nearest: {
    * If the part is `week`, the `weekStartsOn` option can be used to specify the
    * day of the week that the week starts on. The default is 0 (Sunday).
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Rounding DateTime values to nearest units)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3231,6 +3628,9 @@ export const nearest: {
    *   DateTime.formatIso
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   (
    part: DateTime.UnitSingular,
@@ -3242,9 +3642,8 @@ export const nearest: {
    * If the part is `week`, the `weekStartsOn` option can be used to specify the
    * day of the week that the week starts on. The default is 0 (Sunday).
    *
-   * @since 3.6.0
-   * @category math
-   * @example
+   * **Example** (Rounding DateTime values to nearest units)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3254,6 +3653,9 @@ export const nearest: {
    *   DateTime.formatIso
    * )
    * ```
+   *
+   * @category math
+   * @since 3.6.0
    */
   <A extends DateTime>(
    self: A,
@@ -3267,14 +3669,17 @@ export const nearest: {
 // =============================================================================
 
 /**
- * Format a `DateTime` as a string using the `DateTimeFormat` API.
+ * Formats a `DateTime` with `Intl.DateTimeFormat`.
+ *
+ * Unless a `timeZone` option is supplied, UTC values are formatted in UTC and
+ * zoned values are formatted in their named zone or fixed-offset zone.
  *
- * The `timeZone` option is set to the offset of the time zone.
+ * Fixed-offset zones depend on runtime support for offset `timeZone`
+ * identifiers. When unsupported, formatting falls back to UTC with the
+ * `DateTime` adjusted to the offset.
  *
- * Note: On Node versions < 22, fixed "Offset" zones will set the time zone to
- * "UTC" and use the adjusted `Date`.
+ * **Example** (Formatting DateTime values with Intl options)
  *
- * @example
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3291,8 +3696,8 @@ export const nearest: {
  * console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const format: {
   // =============================================================================
@@ -3300,14 +3705,17 @@ export const format: {
   // =============================================================================
 
   /**
-   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   * Formats a `DateTime` with `Intl.DateTimeFormat`.
+   *
+   * Unless a `timeZone` option is supplied, UTC values are formatted in UTC and
+   * zoned values are formatted in their named zone or fixed-offset zone.
    *
-   * The `timeZone` option is set to the offset of the time zone.
+   * Fixed-offset zones depend on runtime support for offset `timeZone`
+   * identifiers. When unsupported, formatting falls back to UTC with the
+   * `DateTime` adjusted to the offset.
    *
-   * Note: On Node versions < 22, fixed "Offset" zones will set the time zone to
-   * "UTC" and use the adjusted `Date`.
+   * **Example** (Formatting DateTime values with Intl options)
    *
-   * @example
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3324,8 +3732,8 @@ export const format: {
    * console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (
    options?:
@@ -3339,14 +3747,17 @@ export const format: {
   // =============================================================================
 
   /**
-   * Format a `DateTime` as a string using the `DateTimeFormat` API.
+   * Formats a `DateTime` with `Intl.DateTimeFormat`.
+   *
+   * Unless a `timeZone` option is supplied, UTC values are formatted in UTC and
+   * zoned values are formatted in their named zone or fixed-offset zone.
    *
-   * The `timeZone` option is set to the offset of the time zone.
+   * Fixed-offset zones depend on runtime support for offset `timeZone`
+   * identifiers. When unsupported, formatting falls back to UTC with the
+   * `DateTime` adjusted to the offset.
    *
-   * Note: On Node versions < 22, fixed "Offset" zones will set the time zone to
-   * "UTC" and use the adjusted `Date`.
+   * **Example** (Formatting DateTime values with Intl options)
    *
-   * @example
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3363,8 +3774,8 @@ export const format: {
    * console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (
    self: DateTime,
@@ -3381,7 +3792,8 @@ export const format: {
  *
  * It will use the system's local time zone & locale.
  *
- * @example
+ * **Example** (Formatting DateTime values locally)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3399,8 +3811,8 @@ export const format: {
  * console.log(local) // Output depends on system locale/timezone
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatLocal: {
   /**
@@ -3408,7 +3820,8 @@ export const formatLocal: {
    *
    * It will use the system's local time zone & locale.
    *
-   * @example
+   * **Example** (Formatting DateTime values locally)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3426,8 +3839,8 @@ export const formatLocal: {
    * console.log(local) // Output depends on system locale/timezone
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (
    options?:
@@ -3441,7 +3854,8 @@ export const formatLocal: {
    *
    * It will use the system's local time zone & locale.
    *
-   * @example
+   * **Example** (Formatting DateTime values locally)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3459,8 +3873,8 @@ export const formatLocal: {
    * console.log(local) // Output depends on system locale/timezone
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (
    self: DateTime,
@@ -3477,7 +3891,8 @@ export const formatLocal: {
  *
  * This forces the time zone to be UTC.
  *
- * @example
+ * **Example** (Formatting DateTime values in UTC)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3498,8 +3913,8 @@ export const formatLocal: {
  * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatUtc: {
   /**
@@ -3507,7 +3922,8 @@ export const formatUtc: {
    *
    * This forces the time zone to be UTC.
    *
-   * @example
+   * **Example** (Formatting DateTime values in UTC)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3528,8 +3944,8 @@ export const formatUtc: {
    * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (
    options?:
@@ -3543,7 +3959,8 @@ export const formatUtc: {
    *
    * This forces the time zone to be UTC.
    *
-   * @example
+   * **Example** (Formatting DateTime values in UTC)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3564,8 +3981,8 @@ export const formatUtc: {
    * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (
    self: DateTime,
@@ -3580,7 +3997,8 @@ export const formatUtc: {
 /**
  * Format a `DateTime` as a string using the `DateTimeFormat` API.
  *
- * @example
+ * **Example** (Formatting DateTime values with custom formatters)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3600,14 +4018,15 @@ export const formatUtc: {
  * console.log(formatted) // "15. Juni 2024, 16:30"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatIntl: {
   /**
    * Format a `DateTime` as a string using the `DateTimeFormat` API.
    *
-   * @example
+   * **Example** (Formatting DateTime values with custom formatters)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3627,14 +4046,15 @@ export const formatIntl: {
    * console.log(formatted) // "15. Juni 2024, 16:30"
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (format: Intl.DateTimeFormat): (self: DateTime) => string
   /**
    * Format a `DateTime` as a string using the `DateTimeFormat` API.
    *
-   * @example
+   * **Example** (Formatting DateTime values with custom formatters)
+   *
    * ```ts
    * import { DateTime } from "effect"
    *
@@ -3654,8 +4074,8 @@ export const formatIntl: {
    * console.log(formatted) // "15. Juni 2024, 16:30"
    * ```
    *
-   * @since 3.6.0
    * @category formatting
+   * @since 3.6.0
    */
   (self: DateTime, format: Intl.DateTimeFormat): string
 } = Internal.formatIntl
@@ -3665,7 +4085,8 @@ export const formatIntl: {
  *
  * Always returns the UTC representation in ISO 8601 format, ignoring any time zone.
  *
- * @example
+ * **Example** (Formatting DateTime values as ISO strings)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3688,7 +4109,8 @@ export const formatIso: (self: DateTime) => string = Internal.formatIso
  *
  * Returns only the date part (YYYY-MM-DD) after applying time zone adjustments.
  *
- * @example
+ * **Example** (Formatting DateTime values as ISO dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3711,7 +4133,8 @@ export const formatIsoDate: (self: DateTime) => string = Internal.formatIsoDate
  *
  * Returns only the date part (YYYY-MM-DD) in UTC, ignoring any time zone.
  *
- * @example
+ * **Example** (Formatting DateTime values as UTC ISO dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3735,7 +4158,8 @@ export const formatIsoDateUtc: (self: DateTime) => string = Internal.formatIsoDa
  * For `DateTime.Utc`, returns the same as `formatIso`. For `DateTime.Zoned`,
  * includes the time zone offset in the format.
  *
- * @example
+ * **Example** (Formatting DateTime values with offsets)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3758,7 +4182,8 @@ export const formatIsoOffset: (self: DateTime) => string = Internal.formatIsoOff
  *
  * It uses the format: `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`.
  *
- * @example
+ * **Example** (Formatting zoned DateTime values)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3777,8 +4202,8 @@ export const formatIsoOffset: (self: DateTime) => string = Internal.formatIsoOff
  * console.log(offsetFormatted) // "2024-06-15T17:30:45.123+03:00"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export const formatIsoZoned: (self: Zoned) => string = Internal.formatIsoZoned
 
@@ -3787,7 +4212,8 @@ export const formatIsoZoned: (self: Zoned) => string = Internal.formatIsoZoned
  *
  * This layer provides the `CurrentTimeZone` service with the specified time zone.
  *
- * @example
+ * **Example** (Providing current time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -3815,7 +4241,8 @@ export const layerCurrentZone: (resource: NoInfer<TimeZone>) => Layer.Layer<Curr
  *
  * This layer provides the `CurrentTimeZone` service with a fixed offset time zone.
  *
- * @example
+ * **Example** (Providing fixed-offset time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -3842,7 +4269,8 @@ export const layerCurrentZoneOffset = (offset: number): Layer.Layer<CurrentTimeZ
  * This layer provides the `CurrentTimeZone` service with a named time zone.
  * If the time zone identifier is invalid, the layer will fail.
  *
- * @example
+ * **Example** (Providing named time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -3870,7 +4298,8 @@ export const layerCurrentZoneNamed: (zoneId: string) => Layer.Layer<
  * This layer provides the `CurrentTimeZone` service using the system's
  * configured local time zone.
  *
- * @example
+ * **Example** (Providing local time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *