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

package/src/MutableHashMap.ts

@@ -22,7 +22,6 @@
  * - Iteration: O(n)
  *
  * @since 2.0.0
- * @category data-structures
  */
 import type { NonEmptyArray } from "./Array.ts"
 import * as Equal from "./Equal.ts"
@@ -38,9 +37,17 @@ import { hasProperty } from "./Predicate.ts"
 const TypeId = "~effect/collections/MutableHashMap"
 
 /**
- * @example
+ * A mutable hash map that stores key-value pairs and supports both referential
+ * and Effect structural equality.
+ *
+ * Operations mutate the map in place. Keys that implement `Equal` / `Hash` can
+ * be looked up structurally; other keys use normal JavaScript reference or
+ * primitive equality.
+ *
+ * **Example** (Using a mutable hash map)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * // Create a mutable hash map with string keys and number values
  * const map: MutableHashMap.MutableHashMap<string, number> = MutableHashMap
@@ -63,8 +70,8 @@ const TypeId = "~effect/collections/MutableHashMap"
  * console.log(entries) // [["count", 42], ["total", 100]]
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface MutableHashMap<out K, out V> extends Iterable<[K, V]>, Pipeable, Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -105,9 +112,10 @@ const MutableHashMapProto: Omit<MutableHashMap<unknown, unknown>, "backing" | "b
 /**
  * Creates an empty MutableHashMap.
  *
- * @example
+ * **Example** (Creating an empty map)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.empty<string, number>()
  *
@@ -118,8 +126,8 @@ const MutableHashMapProto: Omit<MutableHashMap<unknown, unknown>, "backing" | "b
  * console.log(MutableHashMap.size(map)) // 2
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty = <K, V>(): MutableHashMap<K, V> => {
   const self = Object.create(MutableHashMapProto)
@@ -131,9 +139,10 @@ export const empty = <K, V>(): MutableHashMap<K, V> => {
 /**
  * Creates a MutableHashMap from a variable number of key-value pairs.
  *
- * @example
+ * **Example** (Creating a map from entries)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(
  *   ["key1", 42],
@@ -145,8 +154,8 @@ export const empty = <K, V>(): MutableHashMap<K, V> => {
  * console.log(MutableHashMap.size(map)) // 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make: <Entries extends Array<readonly [any, any]>>(
   ...entries: Entries
@@ -158,9 +167,10 @@ export const make: <Entries extends Array<readonly [any, any]>>(
 /**
  * Creates a MutableHashMap from an iterable collection of key-value pairs.
  *
- * @example
+ * **Example** (Creating a map from an iterable)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const entries = [
  *   ["apple", 1],
@@ -178,8 +188,8 @@ export const make: <Entries extends Array<readonly [any, any]>>(
  * console.log(MutableHashMap.get(fromMap, "x")) // Some(10)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableHashMap<K, V> => {
   const self = empty<K, V>()
@@ -190,11 +200,15 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
 }
 
 /**
- * Retrieves the value associated with the specified key from the MutableHashMap.
+ * Looks up a key in the `MutableHashMap`.
+ *
+ * Returns `Some(value)` when an equal key is present and `None` when the key is
+ * absent.
+ *
+ * **Example** (Getting a value)
  *
- * @example
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
  *
@@ -206,16 +220,20 @@ export const fromIterable = <K, V>(entries: Iterable<readonly [K, V]>): MutableH
  * console.log(getValue(map)) // Some(42)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const get: {
   /**
-   * Retrieves the value associated with the specified key from the MutableHashMap.
+   * Looks up a key in the `MutableHashMap`.
+   *
+   * Returns `Some(value)` when an equal key is present and `None` when the key is
+   * absent.
+   *
+   * **Example** (Getting a value)
    *
-   * @example
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -227,16 +245,20 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K>(key: K): <V>(self: MutableHashMap<K, V>) => Option.Option<V>
   /**
-   * Retrieves the value associated with the specified key from the MutableHashMap.
+   * Looks up a key in the `MutableHashMap`.
+   *
+   * Returns `Some(value)` when an equal key is present and `None` when the key is
+   * absent.
+   *
+   * **Example** (Getting a value)
    *
-   * @example
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -248,17 +270,21 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K): Option.Option<V>
 } = dual<
   /**
-   * Retrieves the value associated with the specified key from the MutableHashMap.
+   * Looks up a key in the `MutableHashMap`.
+   *
+   * Returns `Some(value)` when an equal key is present and `None` when the key is
+   * absent.
+   *
+   * **Example** (Getting a value)
    *
-   * @example
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -270,16 +296,20 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K>(key: K) => <V>(self: MutableHashMap<K, V>) => Option.Option<V>,
   /**
-   * Retrieves the value associated with the specified key from the MutableHashMap.
+   * Looks up a key in the `MutableHashMap`.
+   *
+   * Returns `Some(value)` when an equal key is present and `None` when the key is
+   * absent.
+   *
+   * **Example** (Getting a value)
    *
-   * @example
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -291,8 +321,8 @@ export const get: {
    * console.log(getValue(map)) // Some(42)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K) => Option.Option<V>
 >(2, <K, V>(self: MutableHashMap<K, V>, key: K): Option.Option<V> => {
@@ -317,11 +347,12 @@ const referentialKeysCache = new WeakMap<any, any>()
 const isSimpleKey = (u: unknown): boolean => typeof u !== "object" && typeof u !== "function"
 
 /**
- * Extracts all keys from the MutableHashMap into an array.
+ * Returns an iterable over the keys in the `MutableHashMap`.
+ *
+ * **Example** (Reading keys)
  *
- * @example
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(
  *   ["apple", 1],
@@ -336,17 +367,18 @@ const isSimpleKey = (u: unknown): boolean => typeof u !== "object" && typeof u !
  * const hasRequiredKeys = allKeys.includes("apple") && allKeys.includes("banana")
  * ```
  *
- * @since 3.8.0
  * @category elements
+ * @since 3.8.0
  */
 export const keys = <K, V>(self: MutableHashMap<K, V>): Iterable<K> => self.backing.keys()
 
 /**
- * Extracts all values from the MutableHashMap into an array.
+ * Returns an iterable over the values in the `MutableHashMap`.
+ *
+ * **Example** (Reading values)
  *
- * @example
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(
  *   ["apple", 1],
@@ -366,8 +398,8 @@ export const keys = <K, V>(self: MutableHashMap<K, V>): Iterable<K> => self.back
  * console.log(largeValues) // [2, 3]
  * ```
  *
- * @since 3.8.0
  * @category elements
+ * @since 3.8.0
  */
 export const values = <K, V>(self: MutableHashMap<K, V>): Iterable<V> => self.backing.values()
 
@@ -389,9 +421,10 @@ const getFromBucket = <K, V>(
 /**
  * Checks if the MutableHashMap contains the specified key.
  *
- * @example
+ * **Example** (Checking for a key)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
  *
@@ -403,16 +436,17 @@ const getFromBucket = <K, V>(
  * console.log(hasKey(map)) // true
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const has: {
   /**
    * Checks if the MutableHashMap contains the specified key.
    *
-   * @example
+   * **Example** (Checking for a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -424,16 +458,17 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K>(key: K): <V>(self: MutableHashMap<K, V>) => boolean
   /**
    * Checks if the MutableHashMap contains the specified key.
    *
-   * @example
+   * **Example** (Checking for a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -445,17 +480,18 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K): boolean
 } = dual<
   /**
    * Checks if the MutableHashMap contains the specified key.
    *
-   * @example
+   * **Example** (Checking for a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -467,16 +503,17 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K>(key: K) => <V>(self: MutableHashMap<K, V>) => boolean,
   /**
    * Checks if the MutableHashMap contains the specified key.
    *
-   * @example
+   * **Example** (Checking for a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["key1", 42], ["key2", 100])
    *
@@ -488,8 +525,8 @@ export const has: {
    * console.log(hasKey(map)) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K) => boolean
 >(2, (self, key) => Option.isSome(get(self, key)))
@@ -498,9 +535,10 @@ export const has: {
  * Sets a key-value pair in the MutableHashMap, mutating the map in place.
  * If the key already exists, its value is updated.
  *
- * @example
+ * **Example** (Setting key-value pairs)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.empty<string, number>()
  *
@@ -521,17 +559,18 @@ export const has: {
  * console.log(MutableHashMap.size(map)) // 3
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const set: {
   /**
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
-   * @example
+   * **Example** (Setting key-value pairs)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.empty<string, number>()
    *
@@ -552,17 +591,18 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(key: K, value: V): (self: MutableHashMap<K, V>) => MutableHashMap<K, V>
   /**
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
-   * @example
+   * **Example** (Setting key-value pairs)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.empty<string, number>()
    *
@@ -583,8 +623,8 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K, value: V): MutableHashMap<K, V>
 } = dual<
@@ -592,9 +632,10 @@ export const set: {
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
-   * @example
+   * **Example** (Setting key-value pairs)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.empty<string, number>()
    *
@@ -615,17 +656,18 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(key: K, value: V) => (self: MutableHashMap<K, V>) => MutableHashMap<K, V>,
   /**
    * Sets a key-value pair in the MutableHashMap, mutating the map in place.
    * If the key already exists, its value is updated.
    *
-   * @example
+   * **Example** (Setting key-value pairs)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.empty<string, number>()
    *
@@ -646,8 +688,8 @@ export const set: {
    * console.log(MutableHashMap.size(map)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K, value: V) => MutableHashMap<K, V>
 >(3, <K, V>(self: MutableHashMap<K, V>, key: K, value: V) => {
@@ -694,9 +736,10 @@ const getRefKey = <K>(
  * Updates the value of the specified key within the MutableHashMap if it exists.
  * If the key doesn't exist, the map remains unchanged.
  *
- * @example
+ * **Example** (Modifying existing values)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(["count", 5], ["total", 100])
  *
@@ -717,17 +760,18 @@ const getRefKey = <K>(
  * increment(map)
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const modify: {
   /**
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Modifying existing values)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5], ["total", 100])
    *
@@ -748,17 +792,18 @@ export const modify: {
    * increment(map)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(key: K, f: (v: V) => V): (self: MutableHashMap<K, V>) => MutableHashMap<K, V>
   /**
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Modifying existing values)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5], ["total", 100])
    *
@@ -779,8 +824,8 @@ export const modify: {
    * increment(map)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K, f: (v: V) => V): MutableHashMap<K, V>
 } = dual<
@@ -788,9 +833,10 @@ export const modify: {
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Modifying existing values)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5], ["total", 100])
    *
@@ -811,17 +857,18 @@ export const modify: {
    * increment(map)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(key: K, f: (v: V) => V) => (self: MutableHashMap<K, V>) => MutableHashMap<K, V>,
   /**
    * Updates the value of the specified key within the MutableHashMap if it exists.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Modifying existing values)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5], ["total", 100])
    *
@@ -842,8 +889,8 @@ export const modify: {
    * increment(map)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K, f: (v: V) => V) => MutableHashMap<K, V>
 >(3, <K, V>(self: MutableHashMap<K, V>, key: K, f: (v: V) => V) => {
@@ -880,10 +927,10 @@ export const modify: {
  * If the function returns Some, the key is set to that value.
  * If the function returns None, the key is removed.
  *
- * @example
+ * **Example** (Updating or removing a key)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
- * import * as Option from "effect/Option"
+ * import { MutableHashMap, Option } from "effect"
  *
  * const map = MutableHashMap.make(["count", 5])
  *
@@ -916,8 +963,8 @@ export const modify: {
  * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const modifyAt: {
   /**
@@ -926,10 +973,10 @@ export const modifyAt: {
    * If the function returns Some, the key is set to that value.
    * If the function returns None, the key is removed.
    *
-   * @example
+   * **Example** (Updating or removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
-   * import * as Option from "effect/Option"
+   * import { MutableHashMap, Option } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5])
    *
@@ -962,8 +1009,8 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(key: K, f: (value: Option.Option<V>) => Option.Option<V>): (self: MutableHashMap<K, V>) => MutableHashMap<K, V>
   /**
@@ -972,10 +1019,10 @@ export const modifyAt: {
    * If the function returns Some, the key is set to that value.
    * If the function returns None, the key is removed.
    *
-   * @example
+   * **Example** (Updating or removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
-   * import * as Option from "effect/Option"
+   * import { MutableHashMap, Option } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5])
    *
@@ -1008,8 +1055,8 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(
     self: MutableHashMap<K, V>,
@@ -1023,10 +1070,10 @@ export const modifyAt: {
    * If the function returns Some, the key is set to that value.
    * If the function returns None, the key is removed.
    *
-   * @example
+   * **Example** (Updating or removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
-   * import * as Option from "effect/Option"
+   * import { MutableHashMap, Option } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5])
    *
@@ -1059,8 +1106,8 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(key: K, f: (value: Option.Option<V>) => Option.Option<V>) => (self: MutableHashMap<K, V>) => MutableHashMap<K, V>,
   /**
@@ -1069,10 +1116,10 @@ export const modifyAt: {
    * If the function returns Some, the key is set to that value.
    * If the function returns None, the key is removed.
    *
-   * @example
+   * **Example** (Updating or removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
-   * import * as Option from "effect/Option"
+   * import { MutableHashMap, Option } from "effect"
    *
    * const map = MutableHashMap.make(["count", 5])
    *
@@ -1105,8 +1152,8 @@ export const modifyAt: {
    * console.log(MutableHashMap.has(map, "new")) // false (42 <= 50)
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(
     self: MutableHashMap<K, V>,
@@ -1130,9 +1177,10 @@ export const modifyAt: {
  * Removes the specified key from the MutableHashMap, mutating the map in place.
  * If the key doesn't exist, the map remains unchanged.
  *
- * @example
+ * **Example** (Removing a key)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(
  *   ["key1", 42],
@@ -1157,17 +1205,18 @@ export const modifyAt: {
  * console.log(MutableHashMap.size(map)) // 1
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const remove: {
   /**
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(
    *   ["key1", 42],
@@ -1192,17 +1241,18 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K>(key: K): <V>(self: MutableHashMap<K, V>) => MutableHashMap<K, V>
   /**
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(
    *   ["key1", 42],
@@ -1227,8 +1277,8 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K): MutableHashMap<K, V>
 } = dual<
@@ -1236,9 +1286,10 @@ export const remove: {
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(
    *   ["key1", 42],
@@ -1263,17 +1314,18 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K>(key: K) => <V>(self: MutableHashMap<K, V>) => MutableHashMap<K, V>,
   /**
    * Removes the specified key from the MutableHashMap, mutating the map in place.
    * If the key doesn't exist, the map remains unchanged.
    *
-   * @example
+   * **Example** (Removing a key)
+   *
    * ```ts
-   * import * as MutableHashMap from "effect/MutableHashMap"
+   * import { MutableHashMap } from "effect"
    *
    * const map = MutableHashMap.make(
    *   ["key1", 42],
@@ -1298,8 +1350,8 @@ export const remove: {
    * console.log(MutableHashMap.size(map)) // 1
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, key: K) => MutableHashMap<K, V>
 >(2, <K, V>(self: MutableHashMap<K, V>, key_: K) => {
@@ -1332,9 +1384,10 @@ export const remove: {
  * Removes all key-value pairs from the MutableHashMap, mutating the map in place.
  * The map becomes empty after this operation.
  *
- * @example
+ * **Example** (Clearing all entries)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.make(
  *   ["key1", 42],
@@ -1355,8 +1408,8 @@ export const remove: {
  * console.log(MutableHashMap.size(map)) // 1
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const clear = <K, V>(self: MutableHashMap<K, V>) => {
   self.backing.clear()
@@ -1367,9 +1420,10 @@ export const clear = <K, V>(self: MutableHashMap<K, V>) => {
 /**
  * Returns the number of key-value pairs in the MutableHashMap.
  *
- * @example
+ * **Example** (Checking map size)
+ *
  * ```ts
- * import * as MutableHashMap from "effect/MutableHashMap"
+ * import { MutableHashMap } from "effect"
  *
  * const map = MutableHashMap.empty<string, number>()
  * console.log(MutableHashMap.size(map)) // 0
@@ -1385,25 +1439,46 @@ export const clear = <K, V>(self: MutableHashMap<K, V>) => {
  * console.log(MutableHashMap.size(map)) // 0
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const size = <K, V>(self: MutableHashMap<K, V>): number => self.backing.size
 
 /**
+ * Returns `true` when the `MutableHashMap` contains no key-value pairs.
+ *
+ * @category predicates
  * @since 2.0.0
  */
 export const isEmpty = <K, V>(self: MutableHashMap<K, V>): boolean => self.backing.size === 0
 
 /**
+ * Runs a callback for each key-value pair in the `MutableHashMap`.
+ *
+ * Iteration follows the backing map's order. The callback receives the value
+ * first and the key second, matching `Map.prototype.forEach`.
+ *
+ * @category traversing
  * @since 2.0.0
  */
 export const forEach: {
   /**
+   * Runs a callback for each key-value pair in the `MutableHashMap`.
+   *
+   * Iteration follows the backing map's order. The callback receives the value
+   * first and the key second, matching `Map.prototype.forEach`.
+   *
+   * @category traversing
    * @since 2.0.0
    */
   <K, V>(f: (value: V, key: K) => void): (self: MutableHashMap<K, V>) => void
   /**
+   * Runs a callback for each key-value pair in the `MutableHashMap`.
+   *
+   * Iteration follows the backing map's order. The callback receives the value
+   * first and the key second, matching `Map.prototype.forEach`.
+   *
+   * @category traversing
    * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, f: (value: V, key: K) => void): void