Skip to content

Particle docs name the field a leading particle lands in, which is only true under the default name order #355

Description

@derek73

Five places describe leading-particle behaviour in terms of which field the piece ends up in. Each is true under the default GIVEN_FIRST and falsified by Policy(name_order=FAMILY_FIRST), which shipped in 2.1:

de la Vega    default: family='de la Vega'   FAMILY_FIRST: family='de',  given='la Vega'
Van Johnson   default: given='Van'           FAMILY_FIRST: family='Van', given='Johnson'
de Mesnil     default: family='de Mesnil'    FAMILY_FIRST: family='de',  given='Mesnil'

The underlying rule is a grouping-stage one that runs before roles are assigned and never consults policy.name_order, so the mechanism claims are all fine — only the field destinations need scoping.

Sites

  • nameparser/_lexicon.py:335-337 — the particles_ambiguous field docstring ("a leading one reads as given")
  • nameparser/_types.py:359PARTICLE_OR_GIVEN
  • docs/usage.rst:120-130
  • docs/concepts.rst:161-164
  • docs/customize.rst:170-181 — "a name starting with it has no given name at all"

Why these five and not the two already fixed

PR #354 corrected the two instances it had itself written (nameparser/config/particles.py and AGENTS.md:136) and deliberately left these. Fixing one of five would be arbitrary, and they want a single sweep in consistent wording.

The pattern to follow is the one #354 landed: lead with the mechanism, then show where the piece lands under the default order, making the order-dependence explicit rather than implied.

Verify every claim against a real parse before rewriting it. #354's review found six docstring claims that were plausible and false — including two written to replace other false claims.

Metadata

Metadata

Assignees

Labels

docsDocumentation fixes and updates

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions