docs: explain how roles get assigned, and what input shapes work

concepts.rst described the data model — string becomes tokens, tokens
carry roles, fields are views — but never the decision procedure. v1's
README did: a vocabulary layer claims words for what they are, wherever
they sit, and a positional layer assigns whatever is left by where it
sits. That framing is what customize.rst's Lexicon/Policy split rests
on, so without it "which container does my setting go in?" is
answerable only by consulting a table.

It also carries three things v1 said and 2.0 had dropped: that an
unrecognized word still gets a sensible role (the positional layer
recognizes nothing), that title/suffix are really pre-nominal and
post-nominal — "Dr." is a title before a name and a suffix after — and
that parsing is deterministic, with no model and no training data, so a
wrong parse is wrong reproducibly and can be fixed by configuration.

usage.rst gains v1 README's "Supported Name Structures". Comma order
was demonstrated once inside a matches() example and described once in
a name_order table cell, so a reader could not learn that "Doe, John"
works without stumbling onto it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: derek73

docs/concepts.rst

@@ -41,6 +41,36 @@ else — tokens, spans, the rest of the roles — carried over unchanged.
 ``str()`` renders the default view; nothing about calling it mutates
 the value you called it on.
 
+Two layers decide the roles
+----------------------------
+
+Roles are not assigned in one pass. A vocabulary layer runs first and
+claims words for what they *are*, wherever they sit: titles, particles,
+conjunctions, recognized suffixes, and anything set off by nickname or
+maiden delimiters. Titles chain, so ``"Asst. Vice Chancellor"`` is one
+title; particles join forward, so ``de la`` attaches to ``Vega``.
+
+Whatever the vocabulary layer has not claimed is left to a positional
+layer, which assigns purely by where a word sits: the first unclaimed
+word is the given name, the last is the family name, and anything
+between them is the middle name. ``name_order`` and an explicit comma
+change what "first" and "last" mean here; nothing else does.
+
+This is the whole parser in two sentences, and it explains its
+character. A word nameparser has never seen still gets a sensible role,
+because the positional layer does not need to recognize anything. The
+same word can play different parts in different places — ``Dr.`` is a
+title before a name and a suffix after it, which is why the field names
+``title`` and ``suffix`` are really "pre-nominal" and "post-nominal".
+And nothing is statistical: there is no model and no training data, so
+the same input always parses the same way, and a parse that is wrong is
+wrong reproducibly, which is what makes it fixable by configuration.
+
+The split also tells you which container a setting belongs in, before
+you look anything up: if you are teaching the parser a *word*, it goes
+in the :class:`~nameparser.Lexicon`; if you are changing how unclaimed
+words are *arranged*, it goes in the :class:`~nameparser.Policy`.
+
 Three containers, three concerns
 --------------------------------
 

docs/usage.rst

@@ -28,6 +28,28 @@ they exist). A name with no fields set is falsy, which is how you tell
     >>> bool(parse("")), bool(parse("   ")), bool(parse("John"))
     (False, False, True)
 
+Input shapes
+-------------
+
+Three arrangements are understood, and every piece of each is optional:
+
+1. ``Title First Middle Middle Last Suffix``
+2. ``Last, Title First Middle Middle[,] Suffix [, Suffix]``
+3. ``Title First Middle Last [,] Suffix [, Suffix]``
+
+A comma before the given name is the signal for family-first order, so
+the second form needs no configuration:
+
+.. doctest::
+
+    >>> parse("de la Vega, Juan Q. Xavier III").family
+    'de la Vega'
+    >>> parse("Doe Jr., John").suffix
+    'Jr.'
+
+For family-first input *without* a comma — common outside Europe — set
+``name_order``; see :doc:`customize`.
+
 Aggregate views
 ----------------