docs: introduce and properly describe the module-level constants

autodata on a re-export can't see the defining module's #: doc
comments, so every module-level constant rendered its TYPE's
docstring -- GIVEN_FIRST et al. showed tuple's 'Built-in immutable
sequence', DEFAULT_NICKNAME_DELIMITERS showed frozenset's constructor
help, UNSET rendered blank. Replace them with manual py:data
directives carrying real descriptions, under two new reference
sub-headings ('Name-order constants' -- stating that name_order
accepts ONLY these three, arbitrary Role tuples raise -- and
'Delimiter defaults'). The customize table's name_order type cell now
says 'one of the three exported order constants' instead of the
tuple[Role, Role, Role] annotation that invited hand-rolled tuples.
The #: comments stay in _policy.py for source readers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

docs/customize.rst

@@ -61,7 +61,7 @@ listed below.
      - Type
      - Effect
    * - ``name_order``
-     - ``tuple[Role, Role, Role]``
+     - one of the three exported order constants
      - Assigns positional (no-comma) input to given/middle/family in
        this order. Use the exported ``GIVEN_FIRST`` (default),
        ``FAMILY_FIRST``, or ``FAMILY_FIRST_GIVEN_LAST`` constants.

docs/modules.rst

@@ -47,18 +47,54 @@ Configuration
 .. autoclass:: nameparser.PolicyPatch
    :members:
 
-.. autodata:: nameparser.UNSET
+.. py:data:: nameparser.UNSET
+
+   Sentinel meaning "this patch does not set this field" — the default
+   of every :class:`~nameparser.PolicyPatch` field, distinguishable
+   from every real value including ``None`` and ``False``.
 
 .. autoclass:: nameparser.PatronymicRule
    :members:
 
-.. autodata:: nameparser.GIVEN_FIRST
+Name-order constants
+^^^^^^^^^^^^^^^^^^^^
+
+The three valid values for ``Policy(name_order=...)``. ``name_order``
+is deliberately restricted to these exported constants — an arbitrary
+tuple of :class:`~nameparser.Role` members raises ``ValueError``,
+because only these three orders have defined assignment semantics.
+
+.. py:data:: nameparser.GIVEN_FIRST
+   :value: (Role.GIVEN, Role.MIDDLE, Role.FAMILY)
+
+   Western order (the default): the first word of positional input is
+   the given name, the last is the family name, everything between is
+   middle.
+
+.. py:data:: nameparser.FAMILY_FIRST
+   :value: (Role.FAMILY, Role.GIVEN, Role.MIDDLE)
+
+   Family name first, given name second, remaining words middle —
+   e.g. Hungarian, or East Asian order.
+
+.. py:data:: nameparser.FAMILY_FIRST_GIVEN_LAST
+   :value: (Role.FAMILY, Role.MIDDLE, Role.GIVEN)
+
+   Family name first, given name *last*, the words between middle —
+   e.g. Vietnamese full-name order.
 
-.. autodata:: nameparser.FAMILY_FIRST
+Delimiter defaults
+^^^^^^^^^^^^^^^^^^
 
-.. autodata:: nameparser.FAMILY_FIRST_GIVEN_LAST
+.. py:data:: nameparser.DEFAULT_NICKNAME_DELIMITERS
+   :value: frozenset({("'", "'"), ('"', '"'), ("(", ")")})
 
-.. autodata:: nameparser.DEFAULT_NICKNAME_DELIMITERS
+   The default :attr:`~nameparser.Policy.nickname_delimiters` set —
+   quotes and parentheses. Build on it for additive customizations,
+   e.g. ``nickname_delimiters=DEFAULT_NICKNAME_DELIMITERS |
+   {("«", "»")}``; to *reroute* a pair to ``maiden``, just list it in
+   :attr:`~nameparser.Policy.maiden_delimiters` (it is dropped from
+   the effective nickname set automatically).
 
 Locales
 ~~~~~~~

nameparser/_policy.py

@@ -21,8 +21,18 @@ class PatronymicRule(StrEnum):
 
 # Order-spec constants (#270). Each reads as its contents because roles
 # are named given/family, not first/last.
+
+#: Western order (the default): the first word of positional input is
+#: the given name, the last is the family name, everything between is
+#: middle. One of the three valid ``Policy(name_order=...)`` values.
 GIVEN_FIRST = (Role.GIVEN, Role.MIDDLE, Role.FAMILY)
+#: Family name first, given name second, remaining words middle
+#: (e.g. Hungarian, or East Asian order). One of the three valid
+#: ``Policy(name_order=...)`` values.
 FAMILY_FIRST = (Role.FAMILY, Role.GIVEN, Role.MIDDLE)
+#: Family name first, given name LAST, words between middle
+#: (e.g. Vietnamese full-name order). One of the three valid
+#: ``Policy(name_order=...)`` values.
 FAMILY_FIRST_GIVEN_LAST = (Role.FAMILY, Role.MIDDLE, Role.GIVEN)
 
 _NAME_ROLES = frozenset({Role.GIVEN, Role.MIDDLE, Role.FAMILY})