effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/PubSub.ts

@@ -663,6 +663,11 @@ export const size = <A>(self: PubSub<A>): Effect.Effect<number> => Effect.sync((
  * Returns the current number of messages retained by the `PubSub` for active
  * subscribers synchronously.
  *
+ * **When to use**
+ *
+ * Use when an immediate `PubSub` size snapshot is needed outside effectful code
+ * and concurrent changes between the check and later use are acceptable.
+ *
  * **Details**
  *
  * Returns `0` after shutdown. Because this is an unsafe synchronous snapshot,
@@ -840,6 +845,11 @@ export const isShutdown = <A>(self: PubSub<A>): Effect.Effect<boolean> => Effect
  * Checks synchronously whether `shutdown` has been called, returning `true`
  * after shutdown and `false` otherwise.
  *
+ * **When to use**
+ *
+ * Use when an immediate `PubSub` shutdown-state snapshot is needed outside
+ * effectful code and racing shutdown changes are acceptable.
+ *
  * **Example** (Checking shutdown synchronously)
  *
  * ```ts
@@ -904,8 +914,8 @@ export const awaitShutdown = <A>(self: PubSub<A>): Effect.Effect<void> => self.s
  *
  * **When to use**
  *
- * Use when publishing from effectful code and the configured PubSub strategy
- * should handle surplus messages.
+ * Use when you need to publish from effectful code and let the configured
+ * PubSub strategy handle surplus messages.
  *
  * **Details**
  *
@@ -947,8 +957,8 @@ export const publish: {
    *
    * **When to use**
    *
-   * Use when publishing from effectful code and the configured PubSub strategy
-   * should handle surplus messages.
+   * Use when you need to publish from effectful code and let the configured
+   * PubSub strategy handle surplus messages.
    *
    * **Details**
    *
@@ -990,8 +1000,8 @@ export const publish: {
    *
    * **When to use**
    *
-   * Use when publishing from effectful code and the configured PubSub strategy
-   * should handle surplus messages.
+   * Use when you need to publish from effectful code and let the configured
+   * PubSub strategy handle surplus messages.
    *
    * **Details**
    *
@@ -1052,8 +1062,8 @@ export const publish: {
  *
  * **When to use**
  *
- * Use when you need a non-blocking synchronous publish attempt and can handle
- * `false` when the message cannot be accepted immediately.
+ * Use when you need a non-blocking synchronous publish attempt where `false`
+ * is an acceptable result when the message cannot be accepted immediately.
  *
  * **Details**
  *
@@ -1095,8 +1105,8 @@ export const publishUnsafe: {
    *
    * **When to use**
    *
-   * Use when you need a non-blocking synchronous publish attempt and can handle
-   * `false` when the message cannot be accepted immediately.
+   * Use when you need a non-blocking synchronous publish attempt where `false`
+   * is an acceptable result when the message cannot be accepted immediately.
    *
    * **Details**
    *
@@ -1138,8 +1148,8 @@ export const publishUnsafe: {
    *
    * **When to use**
    *
-   * Use when you need a non-blocking synchronous publish attempt and can handle
-   * `false` when the message cannot be accepted immediately.
+   * Use when you need a non-blocking synchronous publish attempt where `false`
+   * is an acceptable result when the message cannot be accepted immediately.
    *
    * **Details**
    *
@@ -1376,7 +1386,7 @@ export const publishAll: {
  * })
  * ```
  *
- * @category subscription
+ * @category subscriptions
  * @since 2.0.0
  */
 export const subscribe = <A>(self: PubSub<A>): Effect.Effect<Subscription<A>, never, Scope.Scope> =>
@@ -1444,7 +1454,7 @@ const unsubscribe = <A>(self: Subscription<A>): Effect.Effect<void> =>
  * })
  * ```
  *
- * @category subscription
+ * @category subscriptions
  * @since 4.0.0
  */
 export const take = <A>(self: Subscription<A>): Effect.Effect<A> =>
@@ -1492,7 +1502,7 @@ export const take = <A>(self: Subscription<A>): Effect.Effect<A> =>
  * })
  * ```
  *
- * @category subscription
+ * @category subscriptions
  * @since 4.0.0
  */
 export const takeAll = <A>(self: Subscription<A>): Effect.Effect<Arr.NonEmptyArray<A>> =>
@@ -1571,7 +1581,7 @@ const pollForItem = <A>(self: Subscription<A>) => {
  * })
  * ```
  *
- * @category subscription
+ * @category subscriptions
  * @since 4.0.0
  */
 export const takeUpTo: {
@@ -1607,7 +1617,7 @@ export const takeUpTo: {
    * })
    * ```
    *
-   * @category subscription
+   * @category subscriptions
    * @since 4.0.0
    */
   (max: number): <A>(self: Subscription<A>) => Effect.Effect<Array<A>>
@@ -1643,7 +1653,7 @@ export const takeUpTo: {
    * })
    * ```
    *
-   * @category subscription
+   * @category subscriptions
    * @since 4.0.0
    */
   <A>(self: Subscription<A>, max: number): Effect.Effect<Array<A>>
@@ -1694,7 +1704,7 @@ export const takeUpTo: {
  * })
  * ```
  *
- * @category subscription
+ * @category subscriptions
  * @since 4.0.0
  */
 export const takeBetween: {
@@ -1728,7 +1738,7 @@ export const takeBetween: {
    * })
    * ```
    *
-   * @category subscription
+   * @category subscriptions
    * @since 4.0.0
    */
   (min: number, max: number): <A>(self: Subscription<A>) => Effect.Effect<Array<A>>
@@ -1762,7 +1772,7 @@ export const takeBetween: {
    * })
    * ```
    *
-   * @category subscription
+   * @category subscriptions
    * @since 4.0.0
    */
   <A>(self: Subscription<A>, min: number, max: number): Effect.Effect<Array<A>>
@@ -1864,8 +1874,8 @@ export const remaining = <A>(self: Subscription<A>): Effect.Effect<number> =>
  *
  * **When to use**
  *
- * Use when polling from synchronous code and you can handle the `Option.none()`
- * shutdown case directly.
+ * Use when you need synchronous polling outside a managed workflow and want
+ * shutdown observed as data instead of interruption.
  *
  * **Example** (Checking remaining messages synchronously)
  *

package/src/Pull.ts

@@ -240,8 +240,8 @@ export const catchDone: {
  *
  * **When to use**
  *
- * Use to test a whole pull failure cause for normal completion when you only
- * need a boolean branch and do not need the done payload.
+ * Use when you need to test whether a pull failure cause represents normal
+ * completion and only need a boolean result.
  *
  * @see {@link isDoneFailure} for checking a single `Cause.Reason`
  * @see {@link filterDone} for extracting the `Cause.Done` value from a `Cause`
@@ -258,8 +258,8 @@ export const isDoneCause = <E>(cause: Cause.Cause<E>): boolean => cause.reasons.
  *
  * **When to use**
  *
- * Use as a predicate when traversing `cause.reasons` and you need to identify
- * done completion reasons before handling ordinary failures.
+ * Use when you need to identify done completion reasons while traversing
+ * `cause.reasons`, before handling ordinary failures.
  *
  * @see {@link isDoneCause} for checking an entire `Cause` for any done reason
  * @see {@link filterDone} for extracting the `Cause.Done` value from a `Cause`

package/src/Queue.ts

@@ -553,8 +553,8 @@ export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  *
  * **When to use**
  *
- * Use when producers should not block and message loss is acceptable.
- * Useful when you want to maintain a rolling window of the most recent messages.
+ * Use when you need producer offers not to block and can accept dropping the
+ * oldest messages, such as when maintaining a rolling window of recent values.
  *
  * **Example** (Creating sliding queues)
  *
@@ -588,8 +588,8 @@ export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  *
  * **When to use**
  *
- * Use when producers should not block and existing messages should be preserved,
- * but new messages may be lost when the queue is full.
+ * Use when you need producer offers not to block while preserving existing
+ * queued messages, even if new messages may be dropped when the queue is full.
  *
  * **Example** (Creating dropping queues)
  *
@@ -624,9 +624,8 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  *
  * **When to use**
  *
- * Use when producers should never be blocked; unbounded queues never apply backpressure, so producers
- * can always add messages successfully. This is useful when you want to prioritize
- * producer throughput over memory usage control.
+ * Use when you need producers to add messages without backpressure and accept
+ * unbounded memory growth.
  *
  * **Example** (Creating unbounded queues)
  *
@@ -716,6 +715,11 @@ export const offer = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>): Eff
 /**
  * Adds a message to the queue synchronously. Returns `false` if the queue is done.
  *
+ * **When to use**
+ *
+ * Use when you are already in synchronous queue internals or a performance
+ * boundary where wrapping the mutation in `Effect` is intentionally avoided.
+ *
  * **Gotchas**
  *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
@@ -768,6 +772,11 @@ export const offerUnsafe = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>
  * Adds multiple messages to the queue. Returns the remaining messages that
  * were not added.
  *
+ * **When to use**
+ *
+ * Use when producers can submit a batch at once and need to know which messages
+ * did not fit under the queue's capacity strategy.
+ *
  * **Details**
  *
  * For bounded queues, this operation may suspend if the queue doesn't have
@@ -809,6 +818,11 @@ export const offerAll = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effe
  * Adds multiple messages to the queue synchronously. Returns the remaining messages that
  * were not added.
  *
+ * **When to use**
+ *
+ * Use when queue internals or a performance boundary need a synchronous batch
+ * offer and can handle any messages that do not fit.
+ *
  * **Gotchas**
  *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
@@ -891,7 +905,7 @@ export const offerAllUnsafe = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>)
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 4.0.0
  */
 export const fail = <A, E>(self: Enqueue<A, E>, error: E) => failCause(self, core.causeFail(error))
@@ -918,7 +932,7 @@ export const fail = <A, E>(self: Enqueue<A, E>, error: E) => failCause(self, cor
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 4.0.0
  */
 export const failCause: {
@@ -944,7 +958,7 @@ export const failCause: {
    * })
    * ```
    *
-   * @category Completion
+   * @category completion
    * @since 4.0.0
    */
   <E>(cause: Cause<E>): <A>(self: Enqueue<A, E>) => Effect<boolean>
@@ -970,7 +984,7 @@ export const failCause: {
    * })
    * ```
    *
-   * @category Completion
+   * @category completion
    * @since 4.0.0
    */
   <A, E>(self: Enqueue<A, E>, cause: Cause<E>): Effect<boolean>
@@ -984,6 +998,11 @@ export const failCause: {
  * Fails the queue with a cause synchronously. If the queue is already done, `false` is
  * returned.
  *
+ * **When to use**
+ *
+ * Use when queue completion must be driven from synchronous internals while
+ * preserving the full failure `Cause`.
+ *
  * **Gotchas**
  *
  * This is an unsafe operation that directly modifies the queue without Effect wrapping.
@@ -1006,7 +1025,7 @@ export const failCause: {
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 4.0.0
  */
 export const failCauseUnsafe = <A, E>(self: Enqueue<A, E>, cause: Cause<E>): boolean => {
@@ -1064,7 +1083,7 @@ export const failCauseUnsafe = <A, E>(self: Enqueue<A, E>, cause: Cause<E>): boo
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 4.0.0
  */
 export const end = <A, E>(self: Enqueue<A, E | Done>): Effect<boolean> => failCause(self, core.causeFail(core.Done()))
@@ -1113,7 +1132,7 @@ export const end = <A, E>(self: Enqueue<A, E | Done>): Effect<boolean> => failCa
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 4.0.0
  */
 export const endUnsafe = <A, E>(self: Enqueue<A, E | Done>) => failCauseUnsafe(self, core.causeFail(core.Done()))
@@ -1159,7 +1178,7 @@ export const endUnsafe = <A, E>(self: Enqueue<A, E | Done>) => failCauseUnsafe(s
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 4.0.0
  */
 export const interrupt = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
@@ -1196,7 +1215,7 @@ export const interrupt = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 2.0.0
  */
 export const shutdown = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
@@ -1273,6 +1292,11 @@ export const clear = <A, E>(self: Dequeue<A, E>): Effect<Array<A>, Pull.ExcludeD
  * Takes all currently available messages, waiting until at least one message
  * is available when the queue is empty.
  *
+ * **When to use**
+ *
+ * Use when consumers should process the next non-empty batch of buffered
+ * messages instead of repeatedly taking one message at a time.
+ *
  * **Details**
  *
  * Returns a non-empty array. If the queue completes or fails before a message
@@ -1295,7 +1319,7 @@ export const clear = <A, E>(self: Dequeue<A, E>): Effect<Array<A>, Pull.ExcludeD
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 2.0.0
  */
 export const takeAll = <A, E>(self: Dequeue<A, E>): Effect<Arr.NonEmptyArray<A>, E> =>
@@ -1323,7 +1347,7 @@ export const takeAll = <A, E>(self: Dequeue<A, E>): Effect<Arr.NonEmptyArray<A>,
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 4.0.0
  */
 export const collect = <A, E>(self: Dequeue<A, E | Done>): Effect<Array<A>, Pull.ExcludeDone<E>> =>
@@ -1381,7 +1405,7 @@ export const collect = <A, E>(self: Dequeue<A, E | Done>): Effect<Array<A>, Pull
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 2.0.0
  */
 export const takeN = <A, E>(
@@ -1423,7 +1447,7 @@ export const takeN = <A, E>(
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 2.0.0
  */
 export const takeBetween = <A, E>(
@@ -1473,7 +1497,7 @@ export const takeBetween = <A, E>(
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 2.0.0
  */
 export const take = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
@@ -1511,7 +1535,7 @@ export const take = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 2.0.0
  */
 export const poll = <A, E>(self: Dequeue<A, E>): Effect<Option.Option<A>> =>
@@ -1565,6 +1589,11 @@ export const peek = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
 /**
  * Attempts to take one message from the queue synchronously.
  *
+ * **When to use**
+ *
+ * Use when polling queue internals must not suspend or register a waiting taker,
+ * and `undefined` is an acceptable result for an empty queue.
+ *
  * **Details**
  *
  * Returns an `Exit` for an immediately available message or for the queue's
@@ -1597,7 +1626,7 @@ export const peek = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
  * })
  * ```
  *
- * @category Taking
+ * @category taking
  * @since 4.0.0
  */
 export const takeUnsafe = <A, E>(self: Dequeue<A, E>): Exit<A, E> | undefined => {
@@ -1661,7 +1690,7 @@ export {
    * @see {@link interrupt} for graceful interruption after buffered messages are drained
    * @see {@link shutdown} for immediately discarding buffered messages and resuming pending operations
    *
-   * @category Completion
+   * @category completion
    * @since 4.0.0
    */
   await_ as await
@@ -1702,7 +1731,7 @@ export {
  * })
  * ```
  *
- * @category Size
+ * @category sizes
  * @since 2.0.0
  */
 export const size = <A, E>(self: Dequeue<A, E>): Effect<number> => internalEffect.sync(() => sizeUnsafe(self))
@@ -1727,7 +1756,7 @@ export const size = <A, E>(self: Dequeue<A, E>): Effect<number> => internalEffec
  * })
  * ```
  *
- * @category Size
+ * @category sizes
  * @since 2.0.0
  */
 export const isFull = <A, E>(self: Dequeue<A, E>): Effect<boolean> => internalEffect.sync(() => isFullUnsafe(self))
@@ -1735,6 +1764,11 @@ export const isFull = <A, E>(self: Dequeue<A, E>): Effect<boolean> => internalEf
 /**
  * Returns the current number of buffered messages in the queue synchronously.
  *
+ * **When to use**
+ *
+ * Use when you need an immediate `Queue` size snapshot for diagnostics or
+ * internals and do not need the read wrapped in `Effect`.
+ *
  * **Details**
  *
  * Completed queues report a size of `0`. This unsafe operation reads the queue
@@ -1770,7 +1804,7 @@ export const isFull = <A, E>(self: Dequeue<A, E>): Effect<boolean> => internalEf
  * })
  * ```
  *
- * @category Size
+ * @category sizes
  * @since 4.0.0
  */
 export const sizeUnsafe = <A, E>(self: Dequeue<A, E>): number => self.state._tag === "Done" ? 0 : self.messages.length
@@ -1778,6 +1812,11 @@ export const sizeUnsafe = <A, E>(self: Dequeue<A, E>): number => self.state._tag
 /**
  * Checks whether the queue is full synchronously.
  *
+ * **When to use**
+ *
+ * Use when an immediate `Queue` capacity snapshot is needed outside effectful
+ * code and racing queue changes are acceptable.
+ *
  * **Example** (Checking fullness synchronously)
  *
  * ```ts
@@ -1795,7 +1834,7 @@ export const sizeUnsafe = <A, E>(self: Dequeue<A, E>): number => self.state._tag
  * })
  * ```
  *
- * @category Size
+ * @category sizes
  * @since 4.0.0
  */
 export const isFullUnsafe = <A, E>(self: Dequeue<A, E>): boolean => sizeUnsafe(self) === self.capacity
@@ -1831,7 +1870,7 @@ export const isFullUnsafe = <A, E>(self: Dequeue<A, E>): boolean => sizeUnsafe(s
  * })
  * ```
  *
- * @category Completion
+ * @category completion
  * @since 4.0.0
  */
 export const into: {
@@ -1866,7 +1905,7 @@ export const into: {
    * })
    * ```
    *
-   * @category Completion
+   * @category completion
    * @since 4.0.0
    */
   <A, E>(self: Enqueue<A, E | Done>): <AX, EX extends E, RX>(
@@ -1903,7 +1942,7 @@ export const into: {
    * })
    * ```
    *
-   * @category Completion
+   * @category completion
    * @since 4.0.0
    */
   <AX, E, EX extends E, RX, A>(effect: Effect<AX, EX, RX>, self: Enqueue<A, E | Done>): Effect<boolean, never, RX>

package/src/RcRef.ts

@@ -97,10 +97,6 @@ export interface RcRef<out A, out E = never> extends Pipeable {
 /**
  * Namespace containing type-level members associated with `RcRef`.
  *
- * **When to use**
- *
- * Use to reference type-level members associated with `RcRef`.
- *
  * **Example** (Referencing namespace types)
  *
  * ```ts

package/src/Record.ts

@@ -661,7 +661,7 @@ export const get: {
  * Record.modify(input, "b", f) // Option.none()
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const modify: {
@@ -682,7 +682,7 @@ export const modify: {
    * Record.modify(input, "b", f) // Option.none()
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, A, B>(key: NoInfer<K>, f: (a: A) => B): (self: ReadonlyRecord<K, A>) => Option.Option<Record<K, A | B>>
@@ -703,7 +703,7 @@ export const modify: {
    * Record.modify(input, "b", f) // Option.none()
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, f: (a: A) => B): Option.Option<Record<K, A | B>>
@@ -737,7 +737,7 @@ export const modify: {
  * Record.replace(Record.empty<string>(), "a", 10) // Option.none()
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const replace: {
@@ -759,7 +759,7 @@ export const replace: {
    * Record.replace(Record.empty<string>(), "a", 10) // Option.none()
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, B>(key: NoInfer<K>, b: B): <A>(self: ReadonlyRecord<K, A>) => Option.Option<Record<K, A | B>>
@@ -781,7 +781,7 @@ export const replace: {
    * Record.replace(Record.empty<string>(), "a", 10) // Option.none()
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, A, B>(self: ReadonlyRecord<K, A>, key: NoInfer<K>, b: B): Option.Option<Record<K, A | B>>
@@ -815,7 +815,7 @@ export const replace: {
  * assert.deepStrictEqual(Record.remove({ a: 1, b: 2 }, "a"), { b: 2 })
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const remove: {
@@ -840,7 +840,7 @@ export const remove: {
    * assert.deepStrictEqual(Record.remove({ a: 1, b: 2 }, "a"), { b: 2 })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, X extends K>(key: X): <A>(self: ReadonlyRecord<K, A>) => Record<Exclude<K, X>, A>
@@ -865,7 +865,7 @@ export const remove: {
    * assert.deepStrictEqual(Record.remove({ a: 1, b: 2 }, "a"), { b: 2 })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, A, X extends K>(self: ReadonlyRecord<K, A>, key: X): Record<Exclude<K, X>, A>
@@ -897,7 +897,7 @@ export const remove: {
  * Record.pop(input, "c") // Option.none()
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const pop: {
@@ -917,7 +917,7 @@ export const pop: {
    * Record.pop(input, "c") // Option.none()
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, X extends K>(key: X): <A>(self: ReadonlyRecord<K, A>) => Option.Option<[A, Record<Exclude<K, X>, A>]>
@@ -937,7 +937,7 @@ export const pop: {
    * Record.pop(input, "c") // Option.none()
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, A, X extends K>(self: ReadonlyRecord<K, A>, key: X): Option.Option<[A, Record<Exclude<K, X>, A>]>
@@ -1616,7 +1616,7 @@ export const values = <K extends string, A>(self: ReadonlyRecord<K, A>): Array<A
  * assert.deepStrictEqual(Record.set("c", 5)({ a: 1, b: 2 }), { a: 1, b: 2, c: 5 })
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const set: {
@@ -1633,7 +1633,7 @@ export const set: {
    * assert.deepStrictEqual(Record.set("c", 5)({ a: 1, b: 2 }), { a: 1, b: 2, c: 5 })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, K1 extends K | ((string | symbol) & {}), B>(key: K1, value: B): <A>(self: ReadonlyRecord<K, A>) => Record<K | K1, A | B>
@@ -1650,7 +1650,7 @@ export const set: {
    * assert.deepStrictEqual(Record.set("c", 5)({ a: 1, b: 2 }), { a: 1, b: 2, c: 5 })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <K extends string | symbol, A, K1 extends K | ((string | symbol) & {}), B>(self: ReadonlyRecord<K, A>, key: K1, value: B): Record<K | K1, A | B>

package/src/Redactable.ts

@@ -193,8 +193,8 @@ export function redact(u: unknown): unknown {
  *
  * **When to use**
  *
- * Use when you have already verified the value is `Redactable`, for
- * example with {@link isRedactable}, and want to avoid a second check.
+ * Use when you need to read the redacted representation from a value already
+ * verified as `Redactable`.
  *
  * **Details**
  *