fix: address PR review feedback (docstrings, docs prose, test clarity)

Author: derek73

docs/customize.rst

@@ -79,9 +79,11 @@ Russian data in formal order (``Surname GivenName Patronymic``), enable
     ('Ivan', 'Ivanovich', 'Ivanov')
 
 Detection is anchored on a recognised East-Slavic patronymic suffix
-(``-ovich``, ``-ovna``, ``-evich``, ``-evna``, ``-ichna``, and several
-irregular forms; same patterns in Cyrillic). A comma in the input is treated as
-an explicit field-order declaration and suppresses reordering.
+(``-ovich``, ``-ovna``, ``-evich``, ``-evna``, ``-ichna``, and the irregular
+forms ``-ilyich``, ``-kuzmich``, ``-lukich``, ``-fomich``, ``-fokich``; same
+patterns in Cyrillic). A comma activates the parser's standard
+Last, First Middle path, which already handles Russian formal order —
+reordering is suppressed to avoid a double-transformation.
 
 **Opt-in tradeoff:** when the flag is on, any name whose last token happens to
 end in a patronymic suffix is reordered — including Western names with

nameparser/config/__init__.py

@@ -347,13 +347,18 @@ class Constants:
     If set, detects names in Russian formal order (``Surname GivenName Patronymic``)
     by recognizing a trailing East-Slavic patronymic suffix on the last token, and
     rotates the three name parts so that ``first``/``middle``/``last`` map to
-    given name / patronymic / surname respectively.
+    given name / patronymic / surname respectively.  Detection requires exactly one
+    token in each of first, middle, and last; names with multi-part given names or
+    multiple middle names are left unchanged.
 
     Opt-in because a Western person whose surname happens to end in a patronymic
     suffix (e.g. ``"David Michael Abramovich"``) will be reordered incorrectly
     when the flag is on. Enable only when your data is predominantly Russian
     formal-order names.
 
+    For per-instance control without a shared ``Constants``, pass a dedicated
+    instance: ``HumanName("...", constants=Constants(patronymic_name_order=True))``.
+
     .. doctest::
 
         >>> from nameparser import HumanName

nameparser/parser.py

@@ -648,6 +648,14 @@ def is_an_initial(self, value: str) -> bool:
         return bool(self.C.regexes.initial.match(value))
 
     def is_patronymic(self, piece: str) -> bool:
+        """
+        Return True if ``piece`` ends with a recognised East-Slavic patronymic
+        suffix, checked against both Latin-script and Cyrillic patterns in
+        ``self.C.regexes``.  Latin suffixes: ``-ovich``, ``-ovna``, ``-evich``,
+        ``-evna``, ``-ichna``, and the irregular forms ``-ilyich``, ``-kuzmich``,
+        ``-lukich``, ``-fomich``, ``-fokich``.  Cyrillic equivalents are matched
+        by a separate pattern.
+        """
         return bool(
             self.C.regexes.patronymic.search(piece)
             or self.C.regexes.patronymic_cyrillic.search(piece)
@@ -696,7 +704,9 @@ def handle_patronymic_name_order(self) -> None:
         When patronymic_name_order is enabled, detect Russian formal order
         (Surname GivenName Patronymic) and rotate to Western order.
         Fires only for no-comma, single-token first/middle/last where the last
-        token is a patronymic and the middle token is not.
+        token is a patronymic and the middle token is not.  Title, suffix, and
+        nickname parts do not affect this guard — reordering proceeds regardless
+        of whether they are present.
         """
         if (
             not self._had_comma

tests/test_patronymic_order.py

@@ -158,6 +158,14 @@ def test_suffix_preserved(self) -> None:
         assert n.last == "Ivanov"
         assert n.suffix == "Jr."
 
+    def test_western_patronymic_surname_reordered_when_flag_on(self) -> None:
+        # Documented opt-in tradeoff: a Western name whose last token ends in a
+        # patronymic suffix is reordered incorrectly. Not a bug to fix.
+        n = self.hn("David Michael Abramovich")
+        assert n.first == "Michael"
+        assert n.middle == "Abramovich"
+        assert n.last == "David"
+
 
 class PatronymicNameOrderGuardsTests(HumanNameTestBase):
     """Names that must NOT be reordered even when the flag is on."""
@@ -189,10 +197,11 @@ def test_two_token_name(self) -> None:
         assert n.last == "Abramovich"
 
     def test_no_patronymic(self) -> None:
-        # No patronymic anchor → not reordered
-        n = self.hn("Mogilny Alexander")
-        assert n.first == "Mogilny"
-        assert n.last == "Alexander"
+        # Three tokens but no patronymic suffix on last → not reordered
+        n = self.hn("Ivanov Ivan Petrov")
+        assert n.first == "Ivanov"
+        assert n.middle == "Ivan"
+        assert n.last == "Petrov"
 
     def test_western_name_unchanged(self) -> None:
         n = self.hn("John Michael Smith")
@@ -212,15 +221,6 @@ def test_comma_guard_patronymic_form_surname(self) -> None:
         n = self.hn("Sergeevich, Ivan Petrov")
         assert n.last == "Sergeevich"
 
-    def test_western_patronymic_surname_reordered_when_flag_on(self) -> None:
-        # With the flag ON a western patronymic-form surname is reordered.
-        # This is the documented opt-in tradeoff — not a bug to fix.
-        n = self.hn("David Michael Abramovich")
-        assert n.first == "Michael"
-        assert n.middle == "Abramovich"
-        assert n.last == "David"
-
-
 class PatronymicNameOrderFlagOffTests(HumanNameTestBase):
     """With default Constants (flag=False) nothing changes."""