docs: correct the scope of the period-abbreviation title rule

[derek73]

Documentation-only. No parser change; uv run pytest and the -b doctest build both pass.

What was wrong

usage.rst said the period-abbreviation inference applies to "a leading word", and that "the rule only applies to the leading run". Neither holds for any comma form. _peel_leading_titles runs at the head of the part that carries the given name — NO_COMMA segment 0, SUFFIX_COMMA segment 0, and FAMILY_COMMA segment 1 — so:

parse("Morse, Det. Insp. Jane").title   # 'Det. Insp.'
parse("Smith, Xyz.").title              # 'Xyz.'

This is long-standing, not a 2.x regression — 1.4.0 from PyPI behaves identically. Only the description was wrong. customize.rst repeated the same claim and is corrected to match.

New examples

Major. was the example throughout, and it is not an abbreviation — it is a whole word carrying a stray period, so it never illustrated why a period should mean anything. Foo. Xyz. illustrated less still.

The examples now use Det. Insp. Jane Morse. Detective Inspector is a real rank, both parts are real abbreviations, and neither det nor insp is in the shipped vocabulary — so the example actually exercises the structural inference. A line saying so was added, since previously there was no way for a reader to tell which examples depended on vocabulary and which did not.

Framing

The section now opens with what the period means — a trailing period marks an abbreviation, and the parts of a name that get abbreviated are the ones standing outside it, titles and post-nominals — before stating the rule. That is the background-before-behavior shape the other domain-heavy sections use, and it makes the closing limitation legible: only the title direction is inferred.

That closing paragraph is deliberately prose with no doctest. Whether an unrecognized trailing abbreviation should reach suffix is an open design question (issue to follow), and pinning today's answer in an example would prejudge it.

Also

• AGENTS.md's gotcha still named is_leading_title(), a v1 function deleted at the M11 swap, and repeated the same wrong scope claim. It now records the per-segment scoping, all three call sites, that this is the mechanism behind Should parse("Smith, Jr.") put "Jr." in title rather than suffix? #296, and that the three trailing-period rules in the codebase resolve differently from one another.
• A Documentation bullet in the 2.1.0 release log.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.46%. Comparing base (6a9283e) to head (e661a59).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #315   +/-   ##
=======================================
  Coverage   98.46%   98.46%           
=======================================
  Files          41       41           
  Lines        2803     2803           
=======================================
  Hits         2760     2760           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.