customize.rst says a multi-word entry can never match, but never says the credential is still reachable

[derek73]

The docs are accurate but incomplete in a way that reliably produces a wrong conclusion.

docs/customize.rst:53 says:

Vocabulary entries are matched one word at a time (given_name_titles excepted), so a multi-word entry like titles={"grand moff"} can never match; the constructor warns when it sees one

That is true. What is missing is the next sentence, and its absence is what does the damage: adjacent suffix tokens are reassembled after matching, so a multi-word credential is reachable as its component words even though the phrase is not storable.

parse("John Smith, MD PhD").suffix    # 'MD PhD'
parse("John Smith, CBE MC").suffix    # 'CBE MC'
parse("John Smith, BSc MBA").suffix   # 'BSc MBA'
parse("John Smith, USN Ret.").suffix  # 'USN Ret.'
parse("John Smith, PSM I").suffix     # 'PSM I'

Measured across releases — original behavior, not a recent fix:

input	1.4.0	2.0.0	2.1.0	master
John Smith, MD PhD	'MD PhD'	'MD PhD'	'MD PhD'	'MD PhD'
John Smith, PSM I	'PSM I'	'PSM I'	'PSM I'	'PSM I'

The mechanism is the run predicate is_wholly_suffix (nameparser/_pipeline/_vocab.py:246).

What to add

1. After the multi-word-entry paragraph in customize.rst, note that a multi-word credential is still reachable, and how — the limitation is on storage, not on the shape.

2. The recipe:

   from nameparser import Lexicon, Parser
   parser = Parser(lexicon=Lexicon.default().add(suffix_acronyms={"leed", "ap"}))
   parser.parse("John Smith, LEED AP").suffix   # 'LEED AP'

3. Consider the same note wherever the per-word rule is stated — rules.md:430's suffix Background carries the identical true statement with the identical gap.

Why this is worth fixing rather than shrugging at

The inference from "a multi-word entry is inert" to "a multi-word credential is unparseable" survived #291, an approved design spec, and a full implementation plan that specified a new vocabulary set, a new matching unit, a new predicate and a new Lexicon field. None of them ran the parse. A two-minute measurement would have falsified the premise on the day #291 was filed.

No shipped doc ever stated the false claim — which is the point. A true limitation sitting next to an unstated capability is the shape that produced this, so stating the capability is the fix.

Spun off from #291, closed as working-as-designed.