docs(config[save_config_yaml_with_items]) add NumPy docstring with doctest

why: Function had only a one-line summary with no Parameters, Returns, or
Examples section despite the project requiring full NumPy docstrings and
working doctests on all public functions.
what:
- Add description explaining why this differs from save_config_yaml (preserves
  duplicate top-level keys via ordered pairs)
- Add Parameters and Returns sections per NumPy docstring standard
- Add Examples section with duplicate-section round-trip doctest

Author: tony

src/vcspull/config.py

@@ -882,7 +882,34 @@ def save_config_yaml_with_items(
     config_file_path: pathlib.Path,
     items: list[tuple[str, t.Any]],
 ) -> None:
-    """Persist configuration data while preserving duplicate top-level sections."""
+    """Persist configuration data while preserving duplicate top-level sections.
+
+    Unlike :func:`save_config_yaml`, which loses duplicate keys when given a
+    plain ``dict``, this function accepts ordered ``(label, data)`` pairs so
+    that two workspace-root entries with the same key are each serialised as a
+    separate YAML block.
+
+    Parameters
+    ----------
+    config_file_path : pathlib.Path
+        Destination config file (may be a symlink; the real target is updated).
+    items : list of tuple[str, Any]
+        Ordered ``(section_label, section_data)`` pairs. Each pair becomes one
+        YAML document block in the output.
+
+    Examples
+    --------
+    >>> import pathlib, tempfile
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     p = pathlib.Path(tmp) / "cfg.yaml"
+    ...     save_config_yaml_with_items(p, [
+    ...         ("~/code/", {"flask": "git+https://github.com/pallets/flask.git"}),
+    ...         ("~/code/", {"django": "git+https://github.com/django/django.git"}),
+    ...     ])
+    ...     content = p.read_text(encoding="utf-8")
+    ...     "flask" in content and "django" in content
+    True
+    """
     documents: list[str] = []
 
     for label, section in items: