📝 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.

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.

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.