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

package/src/Ref.ts

@@ -5,7 +5,8 @@
  * mutable variables, Refs are thread-safe and work seamlessly with Effect's concurrency model.
  * They provide atomic operations for safe state management in concurrent programs.
  *
- * @example
+ * **Example** (Managing shared state with refs)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -45,7 +46,8 @@ const TypeId = "~effect/Ref"
  * on shared state. It supports both simple read/write operations and complex
  * atomic transformations.
  *
- * @example
+ * **Example** (Reading and updating a ref)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -66,8 +68,8 @@ const TypeId = "~effect/Ref"
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Ref<in out A> extends Ref.Variance<A>, Pipeable {
   readonly ref: MutableRef.MutableRef<A>
@@ -76,14 +78,15 @@ export interface Ref<in out A> extends Ref.Variance<A>, Pipeable {
 /**
  * The Ref namespace containing type definitions and utilities.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export declare namespace Ref {
   /**
    * Variance interface for Ref types, defining the type parameter constraints.
    *
-   * @example
+   * **Example** (Using invariant refs)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -98,8 +101,8 @@ export declare namespace Ref {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category models
+   * @since 2.0.0
    */
   export interface Variance<in out A> {
     readonly [TypeId]: {
@@ -127,7 +130,8 @@ const RefProto = {
  * This function creates a Ref synchronously without wrapping in Effect.
  * Use this only when you're sure about the safety of immediate creation.
  *
- * @example
+ * **Example** (Creating a ref unsafely)
+ *
  * ```ts
  * import { Ref } from "effect"
  *
@@ -142,8 +146,8 @@ const RefProto = {
  * // Prefer Ref.make for Effect-wrapped creation
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeUnsafe = <A>(value: A): Ref<A> => {
   const self = Object.create(RefProto)
@@ -157,7 +161,8 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
  * @param value - The initial value for the Ref
  * @returns An Effect that creates a new Ref
  *
- * @example
+ * **Example** (Creating a ref)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -168,15 +173,16 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => makeUnsafe(value))
 
 /**
  * Gets the current value of the Ref.
  *
- * @example
+ * **Example** (Getting the current value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -187,15 +193,16 @@ export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => ma
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
 
 /**
  * Sets the value of the Ref to the specified value.
  *
- * @example
+ * **Example** (Setting a value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -215,14 +222,15 @@ export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const set = dual<
   /**
    * Sets the value of the Ref to the specified value.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -242,14 +250,15 @@ export const set = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<void>,
   /**
    * Sets the value of the Ref to the specified value.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -269,8 +278,8 @@ export const set = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<void>
 >(2, <A>(self: Ref<A>, value: A) => Effect.sync(() => MutableRef.set(self.ref, value)))
@@ -280,7 +289,8 @@ export const set = dual<
  *
  * Returns the value that was in the Ref before the update.
  *
- * @example
+ * **Example** (Replacing a value atomically)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -296,8 +306,8 @@ export const set = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const getAndSet = dual<
   /**
@@ -305,7 +315,8 @@ export const getAndSet = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Replacing a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -321,8 +332,8 @@ export const getAndSet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -330,7 +341,8 @@ export const getAndSet = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Replacing a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -346,8 +358,8 @@ export const getAndSet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, value: A) =>
@@ -362,7 +374,8 @@ export const getAndSet = dual<
  *
  * Returns the value that was in the Ref before the update.
  *
- * @example
+ * **Example** (Updating and returning the previous value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -378,8 +391,8 @@ export const getAndSet = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdate = dual<
   /**
@@ -387,7 +400,8 @@ export const getAndUpdate = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Updating and returning the previous value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -403,8 +417,8 @@ export const getAndUpdate = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -412,7 +426,8 @@ export const getAndUpdate = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Updating and returning the previous value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -428,8 +443,8 @@ export const getAndUpdate = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, f: (a: A) => A) =>
@@ -446,7 +461,8 @@ export const getAndUpdate = dual<
  * If it returns `Option.none`, the Ref is left unchanged.
  * Always returns the value that was in the Ref before the attempted update.
  *
- * @example
+ * **Example** (Conditionally updating and returning the previous value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  * import * as Option from "effect/Option"
@@ -476,8 +492,8 @@ export const getAndUpdate = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdateSome = dual<
   /**
@@ -487,7 +503,8 @@ export const getAndUpdateSome = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Always returns the value that was in the Ref before the attempted update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the previous value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -517,8 +534,8 @@ export const getAndUpdateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -528,7 +545,8 @@ export const getAndUpdateSome = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Always returns the value that was in the Ref before the attempted update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the previous value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -558,8 +576,8 @@ export const getAndUpdateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) =>
@@ -577,7 +595,8 @@ export const getAndUpdateSome = dual<
  *
  * This is useful when you want to set a value and immediately get it back in one atomic operation.
  *
- * @example
+ * **Example** (Setting and returning the new value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -602,8 +621,8 @@ export const getAndUpdateSome = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const setAndGet = dual<
   /**
@@ -611,7 +630,8 @@ export const setAndGet = dual<
    *
    * This is useful when you want to set a value and immediately get it back in one atomic operation.
    *
-   * @example
+   * **Example** (Setting and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -636,8 +656,8 @@ export const setAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -645,7 +665,8 @@ export const setAndGet = dual<
    *
    * This is useful when you want to set a value and immediately get it back in one atomic operation.
    *
-   * @example
+   * **Example** (Setting and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -670,8 +691,8 @@ export const setAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, value: A) => Effect.sync(() => self.ref.current = value))
@@ -682,7 +703,8 @@ export const setAndGet = dual<
  * The function receives the current value and returns a tuple of [result, newValue].
  * The Ref is updated with the newValue and the result is returned.
  *
- * @example
+ * **Example** (Modifying a value atomically)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -714,8 +736,8 @@ export const setAndGet = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const modify = dual<
   /**
@@ -724,7 +746,8 @@ export const modify = dual<
    * The function receives the current value and returns a tuple of [result, newValue].
    * The Ref is updated with the newValue and the result is returned.
    *
-   * @example
+   * **Example** (Modifying a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -756,8 +779,8 @@ export const modify = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(f: (a: A) => readonly [B, A]) => (self: Ref<A>) => Effect.Effect<B>,
   /**
@@ -766,7 +789,8 @@ export const modify = dual<
    * The function receives the current value and returns a tuple of [result, newValue].
    * The Ref is updated with the newValue and the result is returned.
    *
-   * @example
+   * **Example** (Modifying a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -798,8 +822,8 @@ export const modify = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(self: Ref<A>, f: (a: A) => readonly [B, A]) => Effect.Effect<B>
 >(2, (self, f) =>
@@ -810,13 +834,17 @@ export const modify = dual<
   }))
 
 /**
- * Atomically modifies the value of the Ref using the given partial function.
+ * Atomically computes a result and optionally updates the value of the `Ref`.
+ *
+ * **Details**
  *
- * The function receives the current value and returns an Option of [result, newValue].
- * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
- * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+ * The callback receives the current value and returns `[result, nextValue]`,
+ * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+ * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+ * unchanged. The returned effect always succeeds with `result`.
+ *
+ * **Example** (Conditionally modifying a value)
  *
- * @example
  * ```ts
  * import { Effect, Ref } from "effect"
  * import * as Option from "effect/Option"
@@ -854,18 +882,22 @@ export const modify = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const modifySome: {
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -903,18 +935,22 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]): (self: Ref<A>) => Effect.Effect<B>
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -952,19 +988,23 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>
 } = dual<
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -1002,18 +1042,22 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]) => (self: Ref<A>) => Effect.Effect<B>,
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -1051,8 +1095,8 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]) => Effect.Effect<B>
 >(2, (self, pf) =>
@@ -1064,7 +1108,8 @@ export const modifySome: {
 /**
  * Atomically updates the value of the Ref using the given function.
  *
- * @example
+ * **Example** (Updating a value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -1087,14 +1132,15 @@ export const modifySome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const update = dual<
   /**
    * Atomically updates the value of the Ref using the given function.
    *
-   * @example
+   * **Example** (Updating a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1117,14 +1163,15 @@ export const update = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<void>,
   /**
    * Atomically updates the value of the Ref using the given function.
    *
-   * @example
+   * **Example** (Updating a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1147,8 +1194,8 @@ export const update = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<void>
 >(2, <A>(self: Ref<A>, f: (a: A) => A) =>
@@ -1159,7 +1206,8 @@ export const update = dual<
 /**
  * Atomically updates the value of the Ref using the given function and returns the new value.
  *
- * @example
+ * **Example** (Updating and returning the new value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -1176,14 +1224,15 @@ export const update = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const updateAndGet = dual<
   /**
    * Atomically updates the value of the Ref using the given function and returns the new value.
    *
-   * @example
+   * **Example** (Updating and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1200,14 +1249,15 @@ export const updateAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
    * Atomically updates the value of the Ref using the given function and returns the new value.
    *
-   * @example
+   * **Example** (Updating and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1224,8 +1274,8 @@ export const updateAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, f: (a: A) => A) => Effect.sync(() => self.ref.current = f(self.ref.current)))
@@ -1236,7 +1286,8 @@ export const updateAndGet = dual<
  * If the partial function returns `Option.some`, the Ref is updated with the new value.
  * If it returns `Option.none`, the Ref is left unchanged.
  *
- * @example
+ * **Example** (Conditionally updating a value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  * import * as Option from "effect/Option"
@@ -1265,8 +1316,8 @@ export const updateAndGet = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const updateSome = dual<
   /**
@@ -1275,7 +1326,8 @@ export const updateSome = dual<
    * If the partial function returns `Option.some`, the Ref is updated with the new value.
    * If it returns `Option.none`, the Ref is left unchanged.
    *
-   * @example
+   * **Example** (Conditionally updating a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -1304,8 +1356,8 @@ export const updateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(f: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<void>,
   /**
@@ -1314,7 +1366,8 @@ export const updateSome = dual<
    * If the partial function returns `Option.some`, the Ref is updated with the new value.
    * If it returns `Option.none`, the Ref is left unchanged.
    *
-   * @example
+   * **Example** (Conditionally updating a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -1343,8 +1396,8 @@ export const updateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => Option.Option<A>) => Effect.Effect<void>
 >(2, <A>(self: Ref<A>, f: (a: A) => Option.Option<A>) =>
@@ -1362,7 +1415,8 @@ export const updateSome = dual<
  * If it returns `Option.none`, the Ref is left unchanged.
  * Returns the current value of the Ref after the potential update.
  *
- * @example
+ * **Example** (Conditionally updating and returning the current value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  * import * as Option from "effect/Option"
@@ -1386,8 +1440,8 @@ export const updateSome = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const updateSomeAndGet = dual<
   /**
@@ -1397,7 +1451,8 @@ export const updateSomeAndGet = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Returns the current value of the Ref after the potential update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the current value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -1421,8 +1476,8 @@ export const updateSomeAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -1432,7 +1487,8 @@ export const updateSomeAndGet = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Returns the current value of the Ref after the potential update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the current value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    * import * as Option from "effect/Option"
@@ -1456,8 +1512,8 @@ export const updateSomeAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) =>
@@ -1475,7 +1531,8 @@ export const updateSomeAndGet = dual<
  * This function reads the current value without wrapping in Effect.
  * Use this only when you're sure about the safety of immediate access.
  *
- * @example
+ * **Example** (Reading a ref unsafely)
+ *
  * ```ts
  * import { Ref } from "effect"
  *
@@ -1490,7 +1547,7 @@ export const updateSomeAndGet = dual<
  * // Prefer Ref.get for Effect-wrapped access
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const getUnsafe = <A>(self: Ref<A>): A => self.ref.current