From c8bee95088e387ec51114b6169e8ae45201796de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thomas=20M=C3=BCller?= <thomas.mi.iller.gitea.tmu@gmail.com>
Date: Wed, 23 Sep 2026 22:25:39 +0000
Subject: [PATCH] :memo: Document when to use each matcher

Add the universe/return axes and a "Use when" column to the README API
table, and the same one-liner to each of the four factory JSDoc blocks.
---
 README.md              | 24 ++++++++++++++----------
 src/primitive-union.ts | 10 +++++++---
 src/tagged-union.ts    | 11 ++++++++---
 3 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index ed02e3f..a7abf31 100644
--- a/README.md
+++ b/README.md
@@ -21,17 +21,21 @@ for the design decisions and [Caveats](#caveats) for the limits.
 
 ## API
 
-The package exports four factories. Each comes in a _strict_ variant (one common
-return type `R`) and a _widening_ variant: the `W` suffix means **widening** —
-the return value is widened from one common `R` to the union of every handler's
-return type.
+The package exports four factories. Two axes pick one:
 
-| Factory                          | Return of the matcher            |
-| -------------------------------- | -------------------------------- |
-| `getPrimitiveUnionMatcher<T>()`  | one common `R`                   |
-| `getPrimitiveUnionMatcherW<T>()` | the union of the handler returns |
-| `getTaggedUnionMatcher<T>()`     | one common `R`                   |
-| `getTaggedUnionMatcherW<T>()`    | the union of the handler returns |
+- **Universe** — a _primitive-union_ matcher matches a value that is itself a
+  finite union (`"yes" | "no"`); a _tagged-union_ matcher matches an object
+  discriminated by a property (`{ kind: … }`).
+- **Return** — the _strict_ variant gives every handler one common return type
+  `R`; the _widening_ variant (`W`) widens the return value to the union of the
+  handler returns.
+
+| Factory                          | Use when                                                                  | Return                |
+| -------------------------------- | ------------------------------------------------------------------------- | --------------------- |
+| `getPrimitiveUnionMatcher<T>()`  | the value is the union and all handlers return the same type              | one common `R`        |
+| `getPrimitiveUnionMatcherW<T>()` | the value is the union and handlers return different types                | union of the handlers |
+| `getTaggedUnionMatcher<T>()`     | the value is a discriminated object and all handlers return the same type | one common `R`        |
+| `getTaggedUnionMatcherW<T>()`    | the value is a discriminated object and handlers return different types   | union of the handlers |
 
 ### Primitive-union matchers
 
diff --git a/src/primitive-union.ts b/src/primitive-union.ts
index 4ef4a5f..622c0d9 100644
--- a/src/primitive-union.ts
+++ b/src/primitive-union.ts
@@ -99,6 +99,9 @@ const dispatch =
 /**
  * Create a matcher for a finite primitive universe, with one common return type.
  *
+ * Use it when the value itself is the union (`"yes" | "no"`) and every handler
+ * returns the same type.
+ *
  * The universe `T` must be a finite union of literals with no
  * value/stringification collision: broad members (`string`, `number`, template
  * literals) and `true | "true"` / `1 | "1"` are rejected at the call site. The
@@ -122,9 +125,10 @@ export const getPrimitiveUnionMatcher = <
  * Create a matcher for a finite primitive universe whose return type is the
  * union of every handler's return type.
  *
- * The widening counterpart of {@link getPrimitiveUnionMatcher}: use it when the
- * handlers return different types and the union, not one common `R`, is wanted.
- * The universe constraint and the optional fallback are identical.
+ * Use it when the value itself is the union (`"yes" | "no"`) and the handlers
+ * return different types. The `W` (widening) counterpart of
+ * {@link getPrimitiveUnionMatcher}; the universe constraint and the optional
+ * fallback are identical.
  *
  * @typeParam T - The finite universe of primitive members to match.
  * @returns A builder for the handler map, or the handler map plus a fallback.
diff --git a/src/tagged-union.ts b/src/tagged-union.ts
index 97fd2f6..7a18a29 100644
--- a/src/tagged-union.ts
+++ b/src/tagged-union.ts
@@ -155,6 +155,10 @@ const dispatch =
 /**
  * Create a matcher for a discriminated union, with one common return type.
  *
+ * Use it when the value is an object discriminated by a property
+ * (`{ kind: "circle" } | { kind: "square" }`) and every handler returns the
+ * same type.
+ *
  * The first call fixes the union `T`; the returned function takes the
  * discriminant property's name (`K`, restricted to properties whose values are
  * tags), and that returns the handler-map builder. Supplying a second fallback
@@ -182,9 +186,10 @@ export const getTaggedUnionMatcher = <
  * Create a matcher for a discriminated union whose return type is the union of
  * every handler's return type.
  *
- * The widening counterpart of {@link getTaggedUnionMatcher}: use it when the
- * handlers return different types and the union, not one common `R`, is wanted.
- * The curried key step and the optional fallback are identical.
+ * Use it when the value is a discriminated object and the handlers return
+ * different types. The `W` (widening) counterpart of
+ * {@link getTaggedUnionMatcher}; the curried key step and the optional fallback
+ * are identical.
  *
  * @typeParam T - The discriminated-union type to match.
  * @returns A function that takes the discriminant property's name.