From a0fad62ee7fec780af633a2ae9e4c48e5e5edc16 Mon Sep 17 00:00:00 2001
From: Ilia Alshanetsky <ilia@ilia.ws>
Date: Mon, 12 Oct 2026 13:52:55 -0400
Subject: [PATCH] Clarify parsed-part mutation and fixed dictionary rendering

---
 README.md                 | 14 ++++++++++++++
 src/Part/AbstractPart.php | 11 +++++------
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 74c4b17..52b5797 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,20 @@ $parser->parse('Dr. Jane A. Doe DDS')->toArray();
 `lastname` already includes any particle prefix (`de la Torre`);
 `lastname_prefix` is a convenience extract, not a component to prepend.
 
+### Editing parsed parts
+
+`getParts()` returns the part objects used by the `Name`. Calling `setValue()`
+on an ordinary name part updates its normalized output, even after a getter has
+cached it: changing a `Lastname` from `smith` to `jones` changes `getLastname()`
+from `Smith` to `Jones`. Initials also normalize their current value.
+
+Salutations, suffixes, and surname/middle-name prefixes keep the rendered form
+supplied at construction. Their `setValue()` changes only `getValue()`, so a
+suffix constructed from `md` with rendered form `MD` still renders `MD` after
+changing its raw value. Replace these objects through `Name::setParts()` when
+changing their rendered form. Editing parts does not update `getSource()` or
+rerun parsing; parse a revised input string when you need a new interpretation.
+
 ### Joint names
 
 An honorific can cover two people. The parser still returns one `Name`, and the
diff --git a/src/Part/AbstractPart.php b/src/Part/AbstractPart.php
index 115e8f0..c29cad9 100644
--- a/src/Part/AbstractPart.php
+++ b/src/Part/AbstractPart.php
@@ -21,12 +21,11 @@ public function __construct(string|AbstractPart $value)
      * set the value to wrap
      * (can take string or part instance)
      *
-     * Parts are frozen after mapping: the mapper fixes the rendered form at
-     * map time (pre-normalized parts keep their dictionary form, camelcased
-     * parts memoize off the mapped value), so mutating a mapped part leaves
-     * normalize() out of sync with getValue(). The method stays public only
-     * for the released 1.x API (external callers mutate unmapped parts);
-     * Name::getPartner() defensively clones instead of re-pointing values.
+     * Clears the camelcase cache so ordinary name parts normalize the new
+     * value, including parts already returned by a mapper. Initials likewise
+     * normalize their current value. PreNormalized parts are the exception:
+     * setValue() changes their raw value but keeps the rendered form supplied
+     * at construction (salutations, suffixes, and surname/middle-name prefixes).
      */
     public function setValue(string|AbstractPart $value): static
     {