Improve MapRef docs

docs/std/mapref.md

@@ -0,0 +1,60 @@
+---
+id: mapref
+title: MapRef
+---
+
+A total map from a key to a `Ref` of its value.
+
+```scala mdoc:silent
+trait MapRef[F[_], K, V] {
+
+  /**
+   * Access the reference for this Key
+   */
+  def apply(k: K): Ref[F, V]
+}
+```
+
+It is conceptually similar to a `Ref[F, Map[K, V]]`,
+but with better ergonomics when working on a per key basis.
+Note, however, that it does not support atomic updates to multiple keys.
+
+Additionally, some implementations also provide less contention,
+since all operations are performed over individual key-value pairs,
+those could be sharded.
+Thus, multiple concurrent updates may be executed independently to each other;
+as long as their keys belong to different shards.
+
+### In-Memory database
+
+This is probably one of the most common uses of this tool.
+
+```scala mdoc:reset:silent
+//> using lib "org.typelevel::cats-effect:3.4.11"
+
+import cats.effect.IO
+import cats.effect.std.MapRef
+
+type Id
+type Data
+
+trait DatabaseClient[F[_]] {
+  def getDataById(id: Id): F[Option[Data]]
+  def upsertData(id: Id, data: Data): F[Unit]
+}
+
+object DatabaseClient {
+  def inMemory: IO[DatabaseClient[IO]] =
+    MapRef.ofShardedImmutableMap[IO, Id, Data](
+      shardCount = 5 // Arbitrary number of shards just for demonstration.
+    ).map { mapRef =>
+      new DatabaseClient[IO] {
+        override def getDataById(id: Id): IO[Option[Data]] =
+          mapRef(id).get
+
+        override def upsertData(id: Id, data: Data): IO[Unit] =
+          mapRef(id).update(_ => Some(data))
+      }
+    }
+}
+```

kernel/shared/src/main/scala/cats/effect/kernel/Ref.scala

@@ -34,7 +34,11 @@ import cats.syntax.all._
  * mutable data as `AtomicReference#compareAndSet` and friends are dependent upon object
  * reference equality.
  *
- * See also `cats.effect.std.AtomicCell` class from `cats-effect-std` for an alternative.
+ * See also `cats.effect.std.AtomicCell` class from `cats-effect-std` for an alternative that
+ * ensures exclusive access and effectual updates.
+ *
+ * If your contents are an immutable `Map[K, V]`, and all your operations are per-key, consider
+ * using `cats.effect.std.MapRef`.
  */
 abstract class Ref[F[_], A] extends RefSource[F, A] with RefSink[F, A] {
 

std/shared/src/main/scala/cats/effect/std/MapRef.scala

@@ -26,8 +26,15 @@ import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.atomic.AtomicBoolean
 
 /**
- * This is a total map from K to Ref[F, V]. This allows us to use the Ref API backed by a
- * ConcurrentHashMap or similar.
+ * This is a total map from `K` to `Ref[F, V]`.
+ *
+ * It is conceptually similar to a `Ref[F, Map[K, V]]`, but with better ergonomics when working
+ * on a per key basis. Note, however, that it does not support atomic updates to multiple keys.
+ *
+ * Additionally, some implementations also provide less contention, since all operations are
+ * performed over individual key-value pairs, those could be sharded. Thus, multiple concurrent
+ * updates may be executed independently to each other; as long as their keys belong to
+ * different shards.
  */
 trait MapRef[F[_], K, V] extends Function1[K, Ref[F, V]] {