docs: user-facing docstrings across the public API surface

The task pages delegate detail to the reference ('see modules for the
full field list'), but Token/Ambiguity/Lexicon/Policy/Locale had no
class docstrings (autodoc rendered bare constructor signatures), Role
inherited Enum's 'Create a collection of name/value pairs', and no
dataclass field carried a #: doc. Every public class now opens with
what it is / how you get one / how it relates to its neighbors, every
field has a one-line #: doc that renders in the reference, and
parse()/Parser.parse()'s first sentences speak to users instead of
citing spec sections. Maintainer notes stay, demoted below the
user-facing text.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

nameparser/_lexicon.py

@@ -128,16 +128,47 @@ def _normpairs(
 
 @dataclass(frozen=True, slots=True)
 class Lexicon:
+    """The vocabulary a parser matches against: which words are
+    titles, particles, suffixes, and so on. Immutable and hashable.
+    Start from :meth:`default` (the shipped vocabulary) or
+    :meth:`empty`, derive variants with :meth:`add` / :meth:`remove` /
+    ``|`` (union), and pass the result to ``Parser(lexicon=...)``.
+    Entries are normalized at construction -- lowercased, edge periods
+    stripped -- so matching is case-insensitive."""
+
+    #: Pre-nominal titles ("dr", "sir", "capt").
     titles: frozenset[str] = frozenset()
+    #: Titles whose single following name reads as a GIVEN name
+    #: ("sheikh", "sister") rather than a family name.
     given_name_titles: frozenset[str] = frozenset()
+    #: Post-nominal acronym suffixes, matched with or without periods
+    #: ("phd" matches "PhD" and "Ph.D.").
     suffix_acronyms: frozenset[str] = frozenset()
+    #: Post-nominal word suffixes ("jr", "esquire", "iii").
     suffix_words: frozenset[str] = frozenset()
+    #: Subset of suffix_acronyms counted as suffixes only when written
+    #: WITH periods -- their bare forms are common surnames ("ma",
+    #: "do": "Jack Ma" keeps his family name).
     suffix_acronyms_ambiguous: frozenset[str] = frozenset()
+    #: Family-name particles that chain onto the following piece
+    #: ("van", "de", "bin").
     particles: frozenset[str] = frozenset()
+    #: Subset of particles that can also BE a given name: a leading
+    #: one reads as given and records a particle-or-given ambiguity
+    #: ("Van Johnson").
     particles_ambiguous: frozenset[str] = frozenset()
+    #: Words that join surrounding pieces into one ("y", "and", "и").
     conjunctions: frozenset[str] = frozenset()
+    #: Given-name prefixes that bind to the following word to form one
+    #: given name ("abdul" -> "Abdul Salam"); never standalone names.
     bound_given_names: frozenset[str] = frozenset()
+    #: Marker words introducing a birth surname, routed to the maiden
+    #: field ("née", "geb.", "roz.").
     maiden_markers: frozenset[str] = frozenset()
+    #: Lowercase word -> exact-cased replacement used by capitalized()
+    #: ("phd" -> "Ph.D."). Pair-valued: change it with
+    #: dataclasses.replace(), not add()/remove(); read it as a mapping
+    #: via capitalization_exceptions_map.
     # Canonical storage: sorted tuple of (key, value) pairs. The
     # constructor tolerates any Mapping (or pair iterable) at runtime and
     # canonicalizes here; this closes the caller-aliasing hole and keeps

nameparser/_locale.py

@@ -20,8 +20,20 @@
 
 @dataclass(frozen=True, slots=True)
 class Locale:
+    """A named, shareable bundle of vocabulary and behavior for a
+    naming tradition: a lexicon fragment plus a policy patch, applied
+    together by :func:`nameparser.parser_for`. The packs shipped with
+    nameparser live in :mod:`nameparser.locales`; building your own
+    needs no registration -- construct one and pass it to
+    ``parser_for``."""
+
+    #: Identifier, lowercase ``[a-z0-9_]+`` (e.g. "ru", "tr_az").
     code: str
+    #: Vocabulary ADDED to the base parser's lexicon (unioned; a pack
+    #: never removes base vocabulary).
     lexicon: Lexicon
+    #: Behavior changes folded onto the base policy (set-valued fields
+    #: union; scalars override, later pack wins).
     policy: PolicyPatch = PolicyPatch()
 
     # in the class body so @dataclass(slots=True) keeps them

nameparser/_parser.py

@@ -24,12 +24,18 @@
 
 @dataclass(frozen=True, slots=True)
 class Parser:
-    """Immutable, thread-safe, picklable by construction (spec §4): all
-    validity checking happens at construction; a Parser that constructs
-    successfully cannot fail at parse time on any str content. The None
-    field defaults resolve in __post_init__; after construction both
-    fields are always non-None (the annotations state the steady-state
-    truth, hence the assignment ignores on the defaults)."""
+    """A configured name parser: a :class:`Lexicon` (vocabulary) plus
+    a :class:`Policy` (behavior), both defaulted when omitted. Build
+    one when you need non-default configuration, build it once, and
+    call :meth:`parse` many times -- it is immutable, thread-safe, and
+    picklable by construction: all validity checking happens at
+    construction, so a Parser that constructs successfully cannot fail
+    at parse time on any str content.
+
+    (The None field defaults resolve in __post_init__; after
+    construction both fields are always non-None -- the annotations
+    state the steady-state truth, hence the assignment ignores on the
+    defaults.)"""
 
     lexicon: Lexicon = None  # type: ignore[assignment]  # None -> default()
     policy: Policy = None  # type: ignore[assignment]    # None -> Policy()
@@ -55,9 +61,10 @@ def __repr__(self) -> str:
         return f"Parser({self.lexicon!r}, {self.policy!r})"
 
     def parse(self, text: str) -> ParsedName:
-        """Total over str (spec §5a): content never raises; non-str
-        raises TypeError eagerly, with a decode hint for bytes (#245:
-        bytes support ended with 1.x)."""
+        """Parse one name string into a :class:`ParsedName`. Never
+        raises on string content (unparseable input yields empty
+        fields plus ambiguities); non-str raises TypeError eagerly,
+        with a decode hint for bytes (bytes support ended with 1.x)."""
         if isinstance(text, bytes):
             raise TypeError(
                 "parse() takes str, not bytes -- decode first, e.g. "
@@ -75,7 +82,10 @@ def _default_parser() -> Parser:
 
 
 def parse(text: str) -> ParsedName:
-    """Module-level convenience over a lazily created default Parser."""
+    """Parse a name with the default configuration and return a
+    :class:`ParsedName`. Equivalent to ``Parser().parse(text)``; build
+    your own :class:`Parser` (or use :func:`parser_for`) for custom
+    vocabulary or behavior. Never raises on string content."""
     return _default_parser().parse(text)
 
 

nameparser/_policy.py

@@ -48,19 +48,38 @@ def _reject_bare_string_order(value: object) -> None:
 
 @dataclass(frozen=True, slots=True)
 class Policy:
+    """The behavior switches a parser runs with: name order,
+    patronymic rules, delimiter routing, input scrubbing. Immutable
+    and hashable; every field has a safe default, so construct with
+    only what you change -- ``Policy(maiden_delimiters={("(", ")")})``
+    -- and pass the result to ``Parser(policy=...)``."""
+
+    #: How positional (no-comma) input maps onto given/middle/family;
+    #: one of the exported GIVEN_FIRST (default), FAMILY_FIRST,
+    #: FAMILY_FIRST_GIVEN_LAST orders.
     name_order: tuple[Role, Role, Role] = GIVEN_FIRST
+    #: Opt-in detectors that reorder patronymic-shaped names
+    #: (EAST_SLAVIC, TURKIC); usually set via a locale pack.
     patronymic_rules: frozenset[PatronymicRule] = frozenset()
+    #: Folds middle into family instead of splitting them (v1's
+    #: middle_name_as_last).
     middle_as_family: bool = False  # v1's middle_name_as_last
-    # v1 default delimiter set (#273)
+    #: (open, close) pairs whose enclosed content becomes the nickname
+    #: field. Defaults to DEFAULT_NICKNAME_DELIMITERS (#273).
     nickname_delimiters: frozenset[tuple[str, str]] = DEFAULT_NICKNAME_DELIMITERS
-    # empty by default (v1 parity); a pair listed here routes to maiden
-    # AND is dropped from the effective nickname set (maiden wins, see
-    # __post_init__), so maiden_delimiters={("(", ")")} is the whole
-    # parenthesized-maiden recipe (#274)
+    #: (open, close) pairs whose enclosed content becomes the maiden
+    #: field instead; a pair listed here is dropped from the effective
+    #: nickname set (maiden wins, see __post_init__), so
+    #: maiden_delimiters={("(", ")")} is the whole recipe (#274).
     maiden_delimiters: frozenset[tuple[str, str]] = frozenset()
+    #: Separators beyond a comma that split suffix groups (e.g. " - ").
     extra_suffix_delimiters: frozenset[str] = frozenset()
+    #: Allows a post-comma segment to read as a suffix via the lenient
+    #: initial-shaped test; False requires the strict acronym form.
     lenient_comma_suffixes: bool = True
+    #: Removes emoji from the input before parsing.
     strip_emoji: bool = True
+    #: Removes bidirectional control characters before parsing.
     strip_bidi: bool = True  # =False replaces v1's opt-out CONSTANTS.regexes.bidi = False
 
     # in the class body so @dataclass(slots=True) keeps them

nameparser/_types.py

@@ -25,6 +25,12 @@
 
 
 class Role(Enum):
+    """The seven fields of a parsed name, one per :class:`Token`.
+    Declaration order is the canonical field order everywhere
+    (``as_dict()``, ``comparison_key()``, rendering). Pass a member to
+    :meth:`ParsedName.tokens_for`; a member's ``.value`` is the field's
+    string name (``Role.GIVEN.value == "given"``)."""
+
     # Declaration order IS the canonical field order (conventions §3):
     # every listing of the seven fields anywhere derives from this.
     TITLE = "title"
@@ -37,9 +43,15 @@ class Role(Enum):
 
 
 class Span(NamedTuple):
-    """Provenance range into ParsedName.original. end is exclusive."""
+    """Where a :class:`Token` came from: a character range into
+    :attr:`ParsedName.original` such that ``original[start:end]`` is
+    the token's source text (``end`` exclusive). A plain two-int
+    NamedTuple; ``None`` in :attr:`Token.span` marks a synthetic token
+    with no source position."""
 
+    #: First character index (0-based).
     start: int
+    #: One past the last character index.
     end: int
 
     def __add__(self, other: object) -> NoReturn:  # type: ignore[override]
@@ -120,9 +132,23 @@ def _guarded_setstate(self: object, state: dict[str, object]) -> None:
 
 @dataclass(frozen=True, slots=True)
 class Token:
+    """One classified word of a parsed name: its text, where it came
+    from, which field it belongs to, and how it was classified. Read
+    tokens off :attr:`ParsedName.tokens` or
+    :meth:`ParsedName.tokens_for`; you only construct one directly
+    when hand-building a :class:`ParsedName`."""
+
+    #: The word exactly as written in the input (never empty).
     text: str
-    span: Span | None  # None = synthetic (from replace())
+    #: Position in ParsedName.original; None marks a synthetic token
+    #: (e.g. introduced by replace()) with no source position.
+    span: Span | None
+    #: The field this token belongs to.
     role: Role
+    #: Classification labels. Exactly the four in STABLE_TAGS
+    #: ("particle", "conjunction", "initial", "joined") are API;
+    #: namespaced tags like "vocab:..." are unstable debugging
+    #: provenance -- never match against them.
     tags: frozenset[str] = frozenset()
 
     # in the class body so @dataclass(slots=True) keeps them
@@ -187,7 +213,10 @@ def __repr__(self) -> str:
 
 
 class AmbiguityKind(StrEnum):
-    """Stable identifiers (API); members ARE their string values."""
+    """The stable vocabulary of :class:`Ambiguity` kinds. A StrEnum:
+    members ARE their string values, so ``kind == "particle-or-given"``
+    compares directly. New kinds may be added in minor releases;
+    existing values never change meaning."""
 
     ORDER = "order"
     SUFFIX_OR_NICKNAME = "suffix-or-nickname"
@@ -198,8 +227,17 @@ class AmbiguityKind(StrEnum):
 
 @dataclass(frozen=True, slots=True)
 class Ambiguity:
+    """A call the parser made that could legitimately have gone the
+    other way, surfaced on :attr:`ParsedName.ambiguities` instead of
+    silently guessed away. The parse still commits to one reading --
+    an Ambiguity is a flag for review, not an error."""
+
+    #: Which known ambiguity shape this is (stable API values).
     kind: AmbiguityKind
+    #: Human-readable specifics of this occurrence (wording unstable).
     detail: str
+    #: The tokens involved -- always a subset of the owning
+    #: ParsedName's tokens; may be empty (e.g. unbalanced-delimiter).
     tokens: tuple[Token, ...]
 
     # in the class body so @dataclass(slots=True) keeps them
@@ -232,15 +270,25 @@ def __repr__(self) -> str:
 
 @dataclass(frozen=True, slots=True)
 class ParsedName:
-    """Immutable result of a parse. Constructor-enforced invariants:
-    spans ascending, non-overlapping, in bounds of `original`; every
-    Ambiguity's tokens are a subset of `tokens`. Provenance semantics
-    (text == original[span] for parser-produced names) are documented,
-    not enforced -- transforms like replace() legitimately break them.
+    """The immutable result of parsing one name string. Read the seven
+    fields as strings (``.given``, ``.family``, ...); inspect structure
+    through :attr:`tokens` / :meth:`tokens_for`; correct a parse with
+    :meth:`replace` (returns a new value); produce output with
+    :meth:`render`, :meth:`initials`, :meth:`capitalized`, or ``str()``.
+
+    Constructor-enforced invariants: spans ascending, non-overlapping,
+    in bounds of `original`; every Ambiguity's tokens are a subset of
+    `tokens`. Provenance semantics (text == original[span] for
+    parser-produced names) are documented, not enforced -- transforms
+    like replace() legitimately break them.
     """
 
+    #: The input string exactly as passed to parse().
     original: str
+    #: Every classified token, in document order.
     tokens: tuple[Token, ...]
+    #: Judgment calls that could have gone the other way; empty for
+    #: most names (see Ambiguity).
     ambiguities: tuple[Ambiguity, ...] = ()
 
     # in the class body so @dataclass(slots=True) keeps them