effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/DateTime.d.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";
@@ -18,13 +67,18 @@ declare const TimeZoneTypeId = "~effect/time/DateTime/TimeZone";
  * 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";
@@ -32,8 +86,14 @@ export interface Utc extends DateTime.Proto {
     partsUtc: DateTime.PartsWithWeekday | undefined;
 }
 /**
- * @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";
@@ -44,38 +104,71 @@ export interface Zoned extends DateTime.Proto {
     partsUtc: DateTime.PartsWithWeekday | undefined;
 }
 /**
- * @since 3.6.0
+ * Companion namespace containing the public helper types used by `DateTime`
+ * constructors, parts APIs, formatting, and date/time arithmetic.
+ *
  * @category models
+ * @since 3.6.0
  */
 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
      */
     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
      */
     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
      */
     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
      */
     type UnitSingular = "millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "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
      */
     type UnitPlural = "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "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
      */
     interface PartsWithWeekday {
         readonly millisecond: number;
@@ -88,8 +181,12 @@ export declare namespace DateTime {
         readonly year: number;
     }
     /**
-     * @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
      */
     interface Parts {
         readonly millisecond: number;
@@ -101,8 +198,12 @@ export declare namespace DateTime {
         readonly year: number;
     }
     /**
-     * @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
      */
     interface PartsForMath {
         readonly milliseconds: number;
@@ -115,56 +216,90 @@ export declare namespace DateTime {
         readonly years: number;
     }
     /**
-     * @since 4.0.0
+     * Object input representing an absolute instant as milliseconds since the Unix
+     * epoch.
+     *
      * @category models
+     * @since 4.0.0
      */
     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
      */
     interface InstantWithZone {
         readonly timeZoneId: string;
         readonly epochMilliseconds: number;
     }
     /**
-     * @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
      */
     interface Proto extends Pipeable, Inspectable {
         readonly [TypeId]: typeof TypeId;
     }
 }
 /**
- * @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;
 /**
- * @since 3.6.0
+ * Companion namespace containing the public variant and protocol types for
+ * `TimeZone`.
+ *
  * @category models
+ * @since 3.6.0
  */
 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
      */
     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
      */
     interface Offset extends Proto {
         readonly _tag: "Offset";
         readonly offset: number;
     }
     /**
-     * @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
      */
     interface Named extends Proto {
         readonly _tag: "Named";
@@ -188,7 +323,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"
  *
@@ -228,48 +364,50 @@ 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";
 /**
- * @since 3.6.0
+ * Checks whether a value is a `DateTime`.
+ *
  * @category guards
+ * @since 3.6.0
  */
 export declare const isDateTime: (u: unknown) => u is DateTime;
 /**
  * Checks if a value is a `TimeZone`.
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export declare const isTimeZone: (u: unknown) => u is TimeZone;
 /**
  * Checks if a value is an offset-based `TimeZone`.
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export declare const isTimeZoneOffset: (u: unknown) => u is TimeZone.Offset;
 /**
  * Checks if a value is a named `TimeZone` (IANA time zone).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export declare const isTimeZoneNamed: (u: unknown) => u is TimeZone.Named;
 /**
  * Checks if a `DateTime` is a UTC `DateTime` (no time zone information).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export declare const isUtc: (self: DateTime) => self is Utc;
 /**
  * Checks if a `DateTime` is a zoned `DateTime` (has time zone information).
  *
- * @since 3.6.0
  * @category guards
+ * @since 3.6.0
  */
 export declare const isZoned: (self: DateTime) => self is Zoned;
 /**
@@ -278,7 +416,8 @@ export declare const isZoned: (self: DateTime) => self is Zoned;
  * 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"
  *
@@ -300,7 +439,8 @@ export declare const Equivalence: Equ.Equivalence<DateTime>;
  * `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"
  *
@@ -325,7 +465,8 @@ export declare const Order: order.Order<DateTime>;
  * 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"
  *
@@ -348,7 +489,8 @@ export declare 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"
      *
@@ -374,7 +516,8 @@ export declare 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"
      *
@@ -399,7 +542,8 @@ export declare const clamp: {
  *
  * If the `Date` is invalid, an `IllegalArgumentError` will be thrown.
  *
- * @example
+ * **Example** (Creating DateTime values from Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -422,21 +566,26 @@ export declare const fromDateUnsafe: (date: Date) => Utc;
  * - 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 3.6.0
  */
 export declare const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone<A>;
 /**
@@ -453,14 +602,20 @@ export declare const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTim
  * - `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 3.6.0
  */
 export declare const makeZonedUnsafe: (input: DateTime.Input, options?: {
     readonly timeZone?: number | string | TimeZone | undefined;
@@ -468,29 +623,41 @@ export declare const makeZonedUnsafe: (input: DateTime.Input, options?: {
     readonly disambiguation?: Disambiguation | undefined;
 }) => Zoned;
 /**
- * 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 declare const makeZoned: (input: DateTime.Input, options?: {
     readonly timeZone?: number | string | TimeZone | undefined;
@@ -498,39 +665,53 @@ export declare const makeZoned: (input: DateTime.Input, options?: {
     readonly disambiguation?: Disambiguation | undefined;
 }) => Option.Option<Zoned>;
 /**
- * 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 declare const make: <A extends DateTime.Input>(input: A) => Option.Option<DateTime.PreserveZone<A>>;
 /**
- * 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"
  *
@@ -546,31 +727,34 @@ export declare const make: <A extends DateTime.Input>(input: A) => Option.Option
  * console.log(invalid._tag === "None") // true
  * ```
  *
- * @since 3.6.0
  * @category constructors
+ * @since 3.6.0
  */
 export declare const makeZonedFromString: (input: string) => Option.Option<Zoned>;
 /**
  * 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 declare const now: Effect.Effect<Utc>;
 /**
- * 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"
  *
@@ -578,6 +762,9 @@ export declare const now: Effect.Effect<Utc>;
  *   const now = yield* DateTime.now
  * })
  * ```
+ *
+ * @category constructors
+ * @since 3.6.0
  */
 export declare const nowAsDate: Effect.Effect<Date>;
 /**
@@ -586,7 +773,8 @@ export declare const nowAsDate: Effect.Effect<Date>;
  * 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"
  *
@@ -601,9 +789,8 @@ export declare const nowUnsafe: LazyArg<Utc>;
 /**
  * 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"
  *
@@ -614,14 +801,16 @@ export declare const nowUnsafe: LazyArg<Utc>;
  * // set as UTC
  * const utc: DateTime.Utc = DateTime.toUtc(now)
  * ```
+ *
+ * @category time zones
+ * @since 3.13.0
  */
 export declare const toUtc: (self: DateTime) => Utc;
 /**
  * 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"
  *
@@ -633,14 +822,16 @@ export declare const toUtc: (self: DateTime) => Utc;
  *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -652,6 +843,9 @@ export declare const setZone: {
      *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (zone: TimeZone, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -660,9 +854,8 @@ export declare 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"
      *
@@ -674,6 +867,9 @@ export declare const setZone: {
      *   const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (self: DateTime, zone: TimeZone, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -685,9 +881,8 @@ export declare 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"
  *
@@ -698,6 +893,9 @@ export declare const setZone: {
  *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export declare const setZoneOffset: {
     /**
@@ -705,9 +903,8 @@ export declare 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"
      *
@@ -718,6 +915,9 @@ export declare const setZoneOffset: {
      *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (offset: number, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -728,9 +928,8 @@ export declare 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"
      *
@@ -741,6 +940,9 @@ export declare const setZoneOffset: {
      *   const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (self: DateTime, offset: number, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -752,7 +954,8 @@ export declare 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"
  *
@@ -766,8 +969,8 @@ export declare const setZoneOffset: {
  * // DateTime.zoneMakeNamedUnsafe("Invalid/Zone")
  * ```
  *
- * @since 3.6.0
  * @category time zones
+ * @since 3.6.0
  */
 export declare const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named;
 /**
@@ -776,7 +979,8 @@ export declare const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named;
  * 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"
  *
@@ -797,7 +1001,8 @@ export declare const zoneMakeOffset: (offset: number) => TimeZone.Offset;
  *
  * If the time zone is invalid, `None` will be returned.
  *
- * @example
+ * **Example** (Creating optional named time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -817,7 +1022,8 @@ export declare const zoneMakeNamed: (zoneId: string) => Option.Option<TimeZone.N
  *
  * 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"
  *
@@ -838,15 +1044,13 @@ export declare const zoneMakeNamedEffect: (zoneId: string) => Effect.Effect<Time
  * 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
@@ -858,7 +1062,8 @@ export declare const zoneMakeLocal: () => TimeZone.Named;
  *
  * Supports both IANA time zone identifiers and offset formats like "+03:00".
  *
- * @example
+ * **Example** (Parsing time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -878,9 +1083,8 @@ export declare const zoneFromString: (zone: string) => Option.Option<TimeZone>;
 /**
  * Format a `TimeZone` as a string.
  *
- * @since 3.6.0
- * @category time zones
- * @example
+ * **Example** (Formatting time zones)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -890,15 +1094,17 @@ export declare const zoneFromString: (zone: string) => Option.Option<TimeZone>;
  * // Outputs "Europe/London"
  * DateTime.zoneToString(DateTime.zoneMakeNamedUnsafe("Europe/London"))
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export declare const zoneToString: (self: TimeZone) => string;
 /**
  * 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"
  *
@@ -908,15 +1114,17 @@ export declare const zoneToString: (self: TimeZone) => string;
  *   DateTime.setZoneNamed(now, "Europe/London")
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -926,6 +1134,9 @@ export declare const setZoneNamed: {
      *   DateTime.setZoneNamed(now, "Europe/London")
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (zoneId: string, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -935,9 +1146,8 @@ export declare 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"
      *
@@ -947,6 +1157,9 @@ export declare const setZoneNamed: {
      *   DateTime.setZoneNamed(now, "Europe/London")
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (self: DateTime, zoneId: string, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -957,9 +1170,8 @@ export declare 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"
  *
@@ -969,15 +1181,17 @@ export declare const setZoneNamed: {
  *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
  * })
  * ```
+ *
+ * @category time zones
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -987,6 +1201,9 @@ export declare const setZoneNamedUnsafe: {
      *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (zoneId: string, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -996,9 +1213,8 @@ export declare 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"
      *
@@ -1008,6 +1224,9 @@ export declare const setZoneNamedUnsafe: {
      *   DateTime.setZoneNamedUnsafe(now, "Europe/London")
      * })
      * ```
+     *
+     * @category time zones
+     * @since 3.6.0
      */
     (self: DateTime, zoneId: string, options?: {
         readonly adjustForTimeZone?: boolean | undefined;
@@ -1022,9 +1241,8 @@ export declare 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"
  *
@@ -1036,6 +1254,9 @@ export declare const setZoneNamedUnsafe: {
  *   DateTime.distance(now, other)
  * })
  * ```
+ *
+ * @category comparisons
+ * @since 3.6.0
  */
 export declare const distance: {
     /**
@@ -1046,9 +1267,8 @@ export declare 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"
      *
@@ -1060,6 +1280,9 @@ export declare const distance: {
      *   DateTime.distance(now, other)
      * })
      * ```
+     *
+     * @category comparisons
+     * @since 3.6.0
      */
     (other: DateTime): (self: DateTime) => Duration.Duration;
     /**
@@ -1070,9 +1293,8 @@ export declare 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"
      *
@@ -1084,13 +1306,17 @@ export declare const distance: {
      *   DateTime.distance(now, other)
      * })
      * ```
+     *
+     * @category comparisons
+     * @since 3.6.0
      */
     (self: DateTime, other: DateTime): Duration.Duration;
 };
 /**
  * Returns the earlier of two `DateTime` values.
  *
- * @example
+ * **Example** (Selecting the earlier DateTime)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1108,7 +1334,8 @@ export declare const min: {
     /**
      * Returns the earlier of two `DateTime` values.
      *
-     * @example
+     * **Example** (Selecting the earlier DateTime)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -1126,7 +1353,8 @@ export declare const min: {
     /**
      * Returns the earlier of two `DateTime` values.
      *
-     * @example
+     * **Example** (Selecting the earlier DateTime)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -1145,7 +1373,8 @@ export declare const min: {
 /**
  * Returns the later of two `DateTime` values.
  *
- * @example
+ * **Example** (Selecting the later DateTime)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1163,7 +1392,8 @@ export declare const max: {
     /**
      * Returns the later of two `DateTime` values.
      *
-     * @example
+     * **Example** (Selecting the later DateTime)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -1181,7 +1411,8 @@ export declare const max: {
     /**
      * Returns the later of two `DateTime` values.
      *
-     * @example
+     * **Example** (Selecting the later DateTime)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -1200,7 +1431,8 @@ export declare 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"
  *
@@ -1218,7 +1450,8 @@ export declare 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"
      *
@@ -1236,7 +1469,8 @@ export declare 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"
      *
@@ -1255,7 +1489,8 @@ export declare 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"
  *
@@ -1275,7 +1510,8 @@ export declare 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"
      *
@@ -1295,7 +1531,8 @@ export declare 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"
      *
@@ -1316,7 +1553,8 @@ export declare 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"
  *
@@ -1334,7 +1572,8 @@ export declare 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"
      *
@@ -1352,7 +1591,8 @@ export declare 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"
      *
@@ -1371,7 +1611,8 @@ export declare 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"
  *
@@ -1391,7 +1632,8 @@ export declare 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"
      *
@@ -1411,7 +1653,8 @@ export declare 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"
      *
@@ -1432,7 +1675,8 @@ export declare 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"
  *
@@ -1450,7 +1694,8 @@ export declare 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"
      *
@@ -1471,7 +1716,8 @@ export declare 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"
      *
@@ -1495,7 +1741,8 @@ export declare 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"
  *
@@ -1515,7 +1762,8 @@ export declare const isFuture: (self: DateTime) => Effect.Effect<boolean>;
  *
  * This is a synchronous version that uses `Date.now()` directly.
  *
- * @example
+ * **Example** (Checking future DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1535,7 +1783,8 @@ export declare const isFutureUnsafe: (self: DateTime) => boolean;
  *
  * 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"
  *
@@ -1555,7 +1804,8 @@ export declare const isPast: (self: DateTime) => Effect.Effect<boolean>;
  *
  * This is a synchronous version that uses `Date.now()` directly.
  *
- * @example
+ * **Example** (Checking past DateTime values unsafely)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1575,7 +1825,8 @@ export declare const isPastUnsafe: (self: DateTime) => boolean;
  *
  * This always returns the UTC representation, ignoring any time zone information.
  *
- * @example
+ * **Example** (Converting DateTime values to UTC Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1597,7 +1848,8 @@ export declare const toDateUtc: (self: DateTime) => Date;
  * 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"
  *
@@ -1620,7 +1872,8 @@ export declare const toDate: (self: DateTime) => Date;
  * 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"
  *
@@ -1641,7 +1894,8 @@ export declare const zonedOffset: (self: Zoned) => number;
  *
  * The offset is formatted as "±HH:MM".
  *
- * @example
+ * **Example** (Formatting zoned offsets)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1662,7 +1916,8 @@ export declare const zonedOffsetIso: (self: Zoned) => string;
  *
  * This returns the UTC timestamp regardless of any time zone information.
  *
- * @example
+ * **Example** (Reading epoch milliseconds)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1670,7 +1925,6 @@ export declare const zonedOffsetIso: (self: Zoned) => string;
  * const epochMillis = DateTime.toEpochMillis(dt)
  *
  * console.log(epochMillis) // 1704067200000
- * console.log(new Date(epochMillis).toISOString()) // "2024-01-01T00:00:00.000Z"
  * ```
  *
  * @category conversions
@@ -1681,9 +1935,8 @@ export declare const toEpochMillis: (self: DateTime) => number;
  * 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"
  *
@@ -1696,6 +1949,9 @@ export declare const toEpochMillis: (self: DateTime) => number;
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category conversions
+ * @since 3.6.0
  */
 export declare const removeTime: (self: DateTime) => Utc;
 /**
@@ -1703,7 +1959,8 @@ export declare const removeTime: (self: DateTime) => Utc;
  *
  * The parts will be time zone adjusted if the `DateTime` is zoned.
  *
- * @example
+ * **Example** (Reading DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1732,7 +1989,8 @@ export declare const toParts: (self: DateTime) => DateTime.PartsWithWeekday;
  *
  * The parts will always be in UTC, ignoring any time zone information.
  *
- * @example
+ * **Example** (Reading UTC DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1754,17 +2012,18 @@ export declare const toPartsUtc: (self: DateTime) => DateTime.PartsWithWeekday;
  *
  * 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 declare const getPartUtc: {
     /**
@@ -1772,17 +2031,18 @@ export declare 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;
     /**
@@ -1790,17 +2050,18 @@ export declare 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;
 };
@@ -1809,19 +2070,20 @@ export declare 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 declare const getPart: {
     /**
@@ -1829,19 +2091,20 @@ export declare 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;
     /**
@@ -1849,19 +2112,20 @@ export declare 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;
 };
@@ -1870,7 +2134,8 @@ export declare const getPart: {
  *
  * The date will be time zone adjusted for `DateTime.Zoned`.
  *
- * @example
+ * **Example** (Updating DateTime parts)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -1893,7 +2158,8 @@ export declare const setParts: {
      *
      * The date will be time zone adjusted for `DateTime.Zoned`.
      *
-     * @example
+     * **Example** (Updating DateTime parts)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -1916,7 +2182,8 @@ export declare const setParts: {
      *
      * The date will be time zone adjusted for `DateTime.Zoned`.
      *
-     * @example
+     * **Example** (Updating DateTime parts)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -1940,7 +2207,8 @@ export declare 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"
  *
@@ -1962,7 +2230,8 @@ export declare 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"
      *
@@ -1984,7 +2253,8 @@ export declare 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"
      *
@@ -2004,13 +2274,21 @@ export declare const setPartsUtc: {
 };
 declare const CurrentTimeZone_base: Context.ServiceClass<CurrentTimeZone, "effect/DateTime/CurrentTimeZone", TimeZone>;
 /**
- * @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"
  *
  * const program = Effect.gen(function*() {
  *   // Access the current time zone service
- *   const zone = yield* DateTime.CurrentTimeZone.asEffect()
+ *   const zone = yield* DateTime.CurrentTimeZone
  *   console.log(DateTime.zoneToString(zone))
  * })
  *
@@ -2019,8 +2297,8 @@ declare const CurrentTimeZone_base: Context.ServiceClass<CurrentTimeZone, "effec
  * Effect.provide(program, layer)
  * ```
  *
- * @since 3.11.0
  * @category current time zone
+ * @since 3.11.0
  */
 export declare class CurrentTimeZone extends CurrentTimeZone_base {
 }
@@ -2028,9 +2306,8 @@ export declare class CurrentTimeZone extends CurrentTimeZone_base {
  * 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"
  *
@@ -2041,14 +2318,16 @@ export declare class CurrentTimeZone extends CurrentTimeZone_base {
  *   const zoned = yield* DateTime.setZoneCurrent(now)
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export declare const setZoneCurrent: (self: DateTime) => Effect.Effect<Zoned, never, 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"
  *
@@ -2058,14 +2337,16 @@ export declare const setZoneCurrent: (self: DateTime) => Effect.Effect<Zoned, ne
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZone(zone))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -2075,14 +2356,16 @@ export declare 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"
      *
@@ -2092,6 +2375,9 @@ export declare 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>>;
 };
@@ -2099,9 +2385,8 @@ export declare 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"
  *
@@ -2110,54 +2395,63 @@ export declare const withCurrentZone: {
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneLocal)
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export declare const withCurrentZoneLocal: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>;
 /**
  * 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 declare 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>) => Effect.Effect<A, E, Exclude<R, CurrentTimeZone>>;
     /**
      * 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>>;
 };
@@ -2167,9 +2461,8 @@ export declare 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"
  *
@@ -2178,6 +2471,9 @@ export declare const withCurrentZoneOffset: {
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export declare const withCurrentZoneNamed: {
     /**
@@ -2186,9 +2482,8 @@ export declare 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"
      *
@@ -2197,6 +2492,9 @@ export declare 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>) => Effect.Effect<A, E | IllegalArgumentError, Exclude<R, CurrentTimeZone>>;
     /**
@@ -2205,9 +2503,8 @@ export declare 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"
      *
@@ -2216,15 +2513,17 @@ export declare 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>>;
 };
 /**
  * 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"
  *
@@ -2233,6 +2532,9 @@ export declare const withCurrentZoneNamed: {
  *   const now = yield* DateTime.nowInCurrentZone
  * }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
  * ```
+ *
+ * @category current time zone
+ * @since 3.6.0
  */
 export declare const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZone>;
 /**
@@ -2243,7 +2545,8 @@ export declare const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZo
  *
  * Supports `disambiguation` when the new wall clock time is ambiguous.
  *
- * @example
+ * **Example** (Mutating DateTime values with Dates)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2257,8 +2560,8 @@ export declare const nowInCurrentZone: Effect.Effect<Zoned, never, CurrentTimeZo
  * console.log(DateTime.formatIso(modified)) // "2024-01-01T15:30:00.000Z"
  * ```
  *
- * @since 3.6.0
  * @category mapping
+ * @since 3.6.0
  */
 export declare const mutate: {
     /**
@@ -2269,7 +2572,8 @@ export declare const mutate: {
      *
      * Supports `disambiguation` when the new wall clock time is ambiguous.
      *
-     * @example
+     * **Example** (Mutating DateTime values with Dates)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -2283,8 +2587,8 @@ export declare 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, options?: {
         readonly disambiguation?: Disambiguation | undefined;
@@ -2297,7 +2601,8 @@ export declare const mutate: {
      *
      * Supports `disambiguation` when the new wall clock time is ambiguous.
      *
-     * @example
+     * **Example** (Mutating DateTime values with Dates)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -2311,8 +2616,8 @@ export declare 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, f: (date: Date) => void, options?: {
         readonly disambiguation?: Disambiguation | undefined;
@@ -2321,7 +2626,8 @@ export declare 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"
  *
@@ -2336,14 +2642,15 @@ export declare const mutate: {
  * console.log(DateTime.formatIso(modified)) // "2024-01-01T18:00:00.000Z"
  * ```
  *
- * @since 3.6.0
  * @category mapping
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -2358,14 +2665,15 @@ export declare 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"
      *
@@ -2380,8 +2688,8 @@ export declare 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;
 };
@@ -2389,9 +2697,8 @@ export declare 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"
  *
@@ -2400,15 +2707,17 @@ export declare const mutateUtc: {
  *   DateTime.mapEpochMillis((millis) => millis + 10)
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -2417,15 +2726,17 @@ export declare 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"
      *
@@ -2434,16 +2745,21 @@ export declare const mapEpochMillis: {
      *   DateTime.mapEpochMillis((millis) => millis + 10)
      * )
      * ```
+     *
+     * @category mapping
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, f: (millis: number) => number): 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"
  *
@@ -2452,15 +2768,20 @@ export declare const mapEpochMillis: {
  *   DateTime.withDate((date) => date.getTime())
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -2469,15 +2790,20 @@ export declare 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"
      *
@@ -2486,16 +2812,21 @@ export declare const withDate: {
      *   DateTime.withDate((date) => date.getTime())
      * )
      * ```
+     *
+     * @category mapping
+     * @since 3.6.0
      */
     <A>(self: DateTime, f: (date: Date) => A): 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"
  *
@@ -2504,15 +2835,20 @@ export declare const withDate: {
  *   DateTime.withDateUtc((date) => date.getTime())
  * )
  * ```
+ *
+ * @category mapping
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -2521,15 +2857,20 @@ export declare 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"
      *
@@ -2538,18 +2879,24 @@ export declare const withDateUtc: {
      *   DateTime.withDateUtc((date) => date.getTime())
      * )
      * ```
+     *
+     * @category mapping
+     * @since 3.6.0
      */
     <A>(self: DateTime, f: (date: Date) => A): A;
 };
 /**
  * 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)}`,
@@ -2560,6 +2907,9 @@ export declare 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
@@ -2569,12 +2919,15 @@ export declare 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)}`,
@@ -2585,6 +2938,9 @@ export declare 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
@@ -2597,12 +2953,15 @@ export declare 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)}`,
@@ -2613,6 +2972,9 @@ export declare 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
@@ -2626,9 +2988,8 @@ export declare const match: {
 /**
  * Add the given `Duration` to a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Adding durations)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2637,14 +2998,16 @@ export declare const match: {
  *   DateTime.addDuration("5 minutes")
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export declare const addDuration: {
     /**
      * Add the given `Duration` to a `DateTime`.
      *
-     * @since 3.6.0
-     * @category math
-     * @example
+     * **Example** (Adding durations)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -2653,14 +3016,16 @@ export declare const addDuration: {
      *   DateTime.addDuration("5 minutes")
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     (duration: Duration.Input): <A extends DateTime>(self: A) => A;
     /**
      * Add the given `Duration` to a `DateTime`.
      *
-     * @since 3.6.0
-     * @category math
-     * @example
+     * **Example** (Adding durations)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -2669,15 +3034,17 @@ export declare const addDuration: {
      *   DateTime.addDuration("5 minutes")
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, duration: Duration.Input): A;
 };
 /**
  * Subtract the given `Duration` from a `DateTime`.
  *
- * @since 3.6.0
- * @category math
- * @example
+ * **Example** (Subtracting durations)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -2686,14 +3053,16 @@ export declare const addDuration: {
  *   DateTime.subtractDuration("5 minutes")
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export declare const subtractDuration: {
     /**
      * Subtract the given `Duration` from a `DateTime`.
      *
-     * @since 3.6.0
-     * @category math
-     * @example
+     * **Example** (Subtracting durations)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -2702,14 +3071,16 @@ export declare 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"
      *
@@ -2718,6 +3089,9 @@ export declare const subtractDuration: {
      *   DateTime.subtractDuration("5 minutes")
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, duration: Duration.Input): A;
 };
@@ -2727,9 +3101,8 @@ export declare 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"
  *
@@ -2738,6 +3111,9 @@ export declare const subtractDuration: {
  *   DateTime.add({ minutes: 5 })
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export declare const add: {
     /**
@@ -2746,9 +3122,8 @@ export declare 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"
      *
@@ -2757,6 +3132,9 @@ export declare const add: {
      *   DateTime.add({ minutes: 5 })
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     (parts: Partial<DateTime.PartsForMath>): <A extends DateTime>(self: A) => A;
     /**
@@ -2765,9 +3143,8 @@ export declare 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"
      *
@@ -2776,15 +3153,17 @@ export declare const add: {
      *   DateTime.add({ minutes: 5 })
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): 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"
  *
@@ -2793,14 +3172,16 @@ export declare const add: {
  *   DateTime.subtract({ minutes: 5 })
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -2809,14 +3190,16 @@ export declare 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"
      *
@@ -2825,6 +3208,9 @@ export declare const subtract: {
      *   DateTime.subtract({ minutes: 5 })
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, parts: Partial<DateTime.PartsForMath>): A;
 };
@@ -2834,9 +3220,8 @@ export declare 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"
  *
@@ -2846,6 +3231,9 @@ export declare const subtract: {
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export declare const startOf: {
     /**
@@ -2854,9 +3242,8 @@ export declare 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"
      *
@@ -2866,6 +3253,9 @@ export declare const startOf: {
      *   DateTime.formatIso
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     (part: DateTime.UnitSingular, options?: {
         readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
@@ -2876,9 +3266,8 @@ export declare 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"
      *
@@ -2888,6 +3277,9 @@ export declare const startOf: {
      *   DateTime.formatIso
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, part: DateTime.UnitSingular, options?: {
         readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
@@ -2899,9 +3291,8 @@ export declare 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"
  *
@@ -2911,6 +3302,9 @@ export declare const startOf: {
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export declare const endOf: {
     /**
@@ -2919,9 +3313,8 @@ export declare 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"
      *
@@ -2931,6 +3324,9 @@ export declare const endOf: {
      *   DateTime.formatIso
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     (part: DateTime.UnitSingular, options?: {
         readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
@@ -2941,9 +3337,8 @@ export declare 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"
      *
@@ -2953,6 +3348,9 @@ export declare const endOf: {
      *   DateTime.formatIso
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, part: DateTime.UnitSingular, options?: {
         readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
@@ -2964,9 +3362,8 @@ export declare 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"
  *
@@ -2976,6 +3373,9 @@ export declare const endOf: {
  *   DateTime.formatIso
  * )
  * ```
+ *
+ * @category math
+ * @since 3.6.0
  */
 export declare const nearest: {
     /**
@@ -2984,9 +3384,8 @@ export declare 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"
      *
@@ -2996,6 +3395,9 @@ export declare const nearest: {
      *   DateTime.formatIso
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     (part: DateTime.UnitSingular, options?: {
         readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
@@ -3006,9 +3408,8 @@ export declare 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"
      *
@@ -3018,20 +3419,26 @@ export declare const nearest: {
      *   DateTime.formatIso
      * )
      * ```
+     *
+     * @category math
+     * @since 3.6.0
      */
     <A extends DateTime>(self: A, part: DateTime.UnitSingular, options?: {
         readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
     }): A;
 };
 /**
- * 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"
  *
@@ -3048,19 +3455,22 @@ export declare const nearest: {
  * console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -3077,21 +3487,24 @@ export declare const format: {
      * console.log(formatted) // "Saturday, June 15, 2024 at 3:30 PM"
      * ```
      *
-     * @since 3.6.0
      * @category formatting
+     * @since 3.6.0
      */
     (options?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
     } | undefined): (self: DateTime) => string;
     /**
-     * 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"
      *
@@ -3108,8 +3521,8 @@ export declare 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, options?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
@@ -3120,7 +3533,8 @@ export declare const format: {
  *
  * It will use the system's local time zone & locale.
  *
- * @example
+ * **Example** (Formatting DateTime values locally)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3138,8 +3552,8 @@ export declare const format: {
  * console.log(local) // Output depends on system locale/timezone
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export declare const formatLocal: {
     /**
@@ -3147,7 +3561,8 @@ export declare const formatLocal: {
      *
      * It will use the system's local time zone & locale.
      *
-     * @example
+     * **Example** (Formatting DateTime values locally)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -3165,8 +3580,8 @@ export declare const formatLocal: {
      * console.log(local) // Output depends on system locale/timezone
      * ```
      *
-     * @since 3.6.0
      * @category formatting
+     * @since 3.6.0
      */
     (options?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
@@ -3176,7 +3591,8 @@ export declare const formatLocal: {
      *
      * It will use the system's local time zone & locale.
      *
-     * @example
+     * **Example** (Formatting DateTime values locally)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -3194,8 +3610,8 @@ export declare const formatLocal: {
      * console.log(local) // Output depends on system locale/timezone
      * ```
      *
-     * @since 3.6.0
      * @category formatting
+     * @since 3.6.0
      */
     (self: DateTime, options?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
@@ -3206,7 +3622,8 @@ export declare const formatLocal: {
  *
  * This forces the time zone to be UTC.
  *
- * @example
+ * **Example** (Formatting DateTime values in UTC)
+ *
  * ```ts
  * import { DateTime } from "effect"
  *
@@ -3227,8 +3644,8 @@ export declare const formatLocal: {
  * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export declare const formatUtc: {
     /**
@@ -3236,7 +3653,8 @@ export declare const formatUtc: {
      *
      * This forces the time zone to be UTC.
      *
-     * @example
+     * **Example** (Formatting DateTime values in UTC)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -3257,8 +3675,8 @@ export declare const formatUtc: {
      * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
      * ```
      *
-     * @since 3.6.0
      * @category formatting
+     * @since 3.6.0
      */
     (options?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
@@ -3268,7 +3686,8 @@ export declare const formatUtc: {
      *
      * This forces the time zone to be UTC.
      *
-     * @example
+     * **Example** (Formatting DateTime values in UTC)
+     *
      * ```ts
      * import { DateTime } from "effect"
      *
@@ -3289,8 +3708,8 @@ export declare const formatUtc: {
      * console.log(utcFormatted) // "06/15/2024, 02:30 PM UTC"
      * ```
      *
-     * @since 3.6.0
      * @category formatting
+     * @since 3.6.0
      */
     (self: DateTime, options?: Intl.DateTimeFormatOptions & {
         readonly locale?: string | undefined;
@@ -3299,7 +3718,8 @@ export declare 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"
  *
@@ -3319,14 +3739,15 @@ export declare const formatUtc: {
  * console.log(formatted) // "15. Juni 2024, 16:30"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export declare 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"
      *
@@ -3346,14 +3767,15 @@ export declare 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"
      *
@@ -3373,8 +3795,8 @@ export declare 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;
 };
@@ -3383,7 +3805,8 @@ export declare 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"
  *
@@ -3405,7 +3828,8 @@ export declare const formatIso: (self: DateTime) => string;
  *
  * 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"
  *
@@ -3427,7 +3851,8 @@ export declare const formatIsoDate: (self: DateTime) => string;
  *
  * 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"
  *
@@ -3450,7 +3875,8 @@ export declare const formatIsoDateUtc: (self: DateTime) => string;
  * 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"
  *
@@ -3472,7 +3898,8 @@ export declare const formatIsoOffset: (self: DateTime) => string;
  *
  * 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"
  *
@@ -3491,8 +3918,8 @@ export declare const formatIsoOffset: (self: DateTime) => string;
  * console.log(offsetFormatted) // "2024-06-15T17:30:45.123+03:00"
  * ```
  *
- * @since 3.6.0
  * @category formatting
+ * @since 3.6.0
  */
 export declare const formatIsoZoned: (self: Zoned) => string;
 /**
@@ -3500,7 +3927,8 @@ export declare const formatIsoZoned: (self: Zoned) => string;
  *
  * This layer provides the `CurrentTimeZone` service with the specified time zone.
  *
- * @example
+ * **Example** (Providing current time zone layers)
+ *
  * ```ts
  * import { DateTime, Effect } from "effect"
  *
@@ -3525,7 +3953,8 @@ export declare const layerCurrentZone: (resource: NoInfer<TimeZone>) => Layer.La
  *
  * 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"
  *
@@ -3550,7 +3979,8 @@ export declare const layerCurrentZoneOffset: (offset: number) => Layer.Layer<Cur
  * 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"
  *
@@ -3574,7 +4004,8 @@ export declare const layerCurrentZoneNamed: (zoneId: string) => Layer.Layer<Curr
  * 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"
  *