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

package/src/MutableHashMap.ts

@@ -21,8 +21,8 @@
  * - Size: O(1)
  * - Iteration: O(n)
  *
- * @since 2.0.0
  * @category data-structures
+ * @since 2.0.0
  */
 import type { NonEmptyArray } from "./Array.ts"
 import * as Equal from "./Equal.ts"
@@ -38,7 +38,15 @@ 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"
  *
@@ -63,8 +71,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,7 +113,8 @@ 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"
  *
@@ -118,8 +127,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,7 +140,8 @@ 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"
  *
@@ -145,8 +155,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,7 +168,8 @@ 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"
  *
@@ -178,8 +189,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,9 +201,13 @@ 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"
  *
@@ -206,14 +221,18 @@ 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"
    *
@@ -227,14 +246,18 @@ 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"
    *
@@ -248,15 +271,19 @@ 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"
    *
@@ -270,14 +297,18 @@ 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"
    *
@@ -291,8 +322,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,9 +348,10 @@ 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"
  *
@@ -336,15 +368,16 @@ 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"
  *
@@ -366,8 +399,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,7 +422,8 @@ 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"
  *
@@ -403,14 +437,15 @@ 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"
    *
@@ -424,14 +459,15 @@ 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"
    *
@@ -445,15 +481,16 @@ 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"
    *
@@ -467,14 +504,15 @@ 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"
    *
@@ -488,8 +526,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,7 +536,8 @@ 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"
  *
@@ -521,15 +560,16 @@ 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"
    *
@@ -552,15 +592,16 @@ 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"
    *
@@ -583,8 +624,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,7 +633,8 @@ 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"
    *
@@ -615,15 +657,16 @@ 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"
    *
@@ -646,8 +689,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,7 +737,8 @@ 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"
  *
@@ -717,15 +761,16 @@ 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"
    *
@@ -748,15 +793,16 @@ 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"
    *
@@ -779,8 +825,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,7 +834,8 @@ 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"
    *
@@ -811,15 +858,16 @@ 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"
    *
@@ -842,8 +890,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,7 +928,8 @@ 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"
@@ -916,8 +965,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,7 +975,8 @@ 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"
@@ -962,8 +1012,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,7 +1022,8 @@ 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"
@@ -1008,8 +1059,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,7 +1074,8 @@ 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"
@@ -1059,8 +1111,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,7 +1121,8 @@ 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"
@@ -1105,8 +1158,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,7 +1183,8 @@ 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"
  *
@@ -1157,15 +1211,16 @@ 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"
    *
@@ -1192,15 +1247,16 @@ 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"
    *
@@ -1227,8 +1283,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,7 +1292,8 @@ 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"
    *
@@ -1263,15 +1320,16 @@ 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"
    *
@@ -1298,8 +1356,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,7 +1390,8 @@ 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"
  *
@@ -1355,8 +1414,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,7 +1426,8 @@ 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"
  *
@@ -1385,25 +1445,42 @@ 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.
+ *
  * @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`.
+ *
  * @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`.
+   *
    * @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`.
+   *
    * @since 2.0.0
    */
   <K, V>(self: MutableHashMap<K, V>, f: (value: V, key: K) => void): void