Docstring diet: private code keeps prose, not sections; one-line properties

AGENTS.md

@@ -161,13 +161,15 @@ validity range is cited to its primary source; say what you verified and what yo
   as doctests ⚙. A frozen dataclass documents its fields under `Attributes`. A public
   property has a one-line docstring naming the quantity and unit, with
   `# numpydoc ignore=RT01` on the `def` line.
-- **Private code** — any name with a single-underscore component, which numpydoc skips ⚙;
-  a nested function's name starts with an underscore, so it is private too — has no
-  `Parameters`, `Returns`, `Yields`, `Raises` or `Examples` sections (`poe size-check`
-  caps those left ⚙): one summary line, then only what
+- **Private code** — any name with a single-underscore component, which numpydoc skips ⚙
+  — has no `Parameters`, `Returns`, `Yields`, `Raises` or `Examples` sections
+  (`poe size-check` caps those left ⚙): one summary line, then only what
   the signature and annotations don't say — a unit, a valid range, a condition, a
   convention, or why it exists. A function whose name and signature say everything needs
-  no docstring; a non-obvious inner function gets a one-line comment.
+  no docstring; a non-obvious inner function gets a one-line comment. A nested function
+  is private. numpydoc still checks one without a leading underscore, so a nested
+  function that takes parameters or returns a value is named with a leading underscore
+  unless it is returned to callers.
 - Comments explain **why**, never **what**: the physics (or the page with the derivation),
   the numerics (why this quadrature, cutoff or tolerance; where precision is lost), sign,
   unit and normalisation choices, references (DOI, equation), and anything a reader would

docs/dev/tooling.md

@@ -186,8 +186,8 @@ files and functions; `noqa` comments by rule; private names imported across pack
 `__all__` lines; cloned code (windows of 50 tokens seen twice, with names renamed and as
 written) with the file pairs that share most; and ruff's complexity counts. A name is
 private by exactly the rule numpydoc's validation excludes (a single-underscore component
-of `module.qualname`), so the report and `poe docstrings` agree; a nested function is private
-when its name starts with an underscore, as `AGENTS.md` asks.
+of `module.qualname`), so the report and `poe docstrings` agree; both count a nested
+function as private only when its name starts with an underscore.
 
 `poe size-check`, in `poe check` and CI's static job, holds `src/solprop` to the ratchets in
 `tools/size_budget.toml`: the number of private docstrings with numpydoc sections, a

native/src/solprop_native/__init__.py

@@ -875,16 +875,6 @@ def _source_digest(root: Path) -> str:
     ``CMakeLists.txt`` and each C++ source and header under ``src`` and ``include``, the
     paths relative to `root` and sorted bytewise, and the digest is the SHA-256 of the
     record.
-
-    Parameters
-    ----------
-    root
-        The ``native`` directory of a checkout.
-
-    Returns
-    -------
-    str
-        The digest in lowercase hexadecimal.
     """
     paths = ["CMakeLists.txt"]
     for folder in ("src", "include"):
@@ -905,11 +895,8 @@ def _source_digest(root: Path) -> str:
 def _checkout_digest() -> str | None:
     """Return this editable checkout's source digest, computed once per process.
 
-    Returns
-    -------
-    str or None
-        The digest, or ``None`` for an installed wheel, which has no sources beside it
-        and which solprop's metadata pins to its own version.
+    - Returns: the digest, or ``None`` for an installed wheel, which has no sources
+      beside it and which solprop's metadata pins to its own version.
     """
     root = Path(__file__).parents[2]
     return _source_digest(root) if (root / "CMakeLists.txt").is_file() else None

native/src/solprop_native/_allocation.py

@@ -74,13 +74,7 @@ def record(self) -> dict[str, object]:
 
     @classmethod
     def read(cls, data: Mapping[str, object]) -> AllocationClass:
-        """Read a class written by :meth:`record`.
-
-        Raises
-        ------
-        ValueError
-            When `data` is not a class.
-        """
+        """Read a class written by :meth:`record`."""
         try:
             kinds = data["kinds"]
             quota = data.get("quota")

native/src/solprop_native/_budget.py

@@ -98,18 +98,9 @@ def _read_cgroup_cpus(root: Path) -> int | None:
 def cores_in_masks(masks: Sequence[int], cpus: Sequence[int]) -> int:
     """Count the cores, given as CPU bitmasks, that hold any of ``cpus``.
 
-    Parameters
-    ----------
-    masks : sequence of int
-        One bitmask per physical core: bit ``n`` set when CPU ``n`` is one of its
-        hardware threads.
-    cpus : sequence of int
-        The CPU indices the process may run on.
-
-    Returns
-    -------
-    int
-        The number of cores holding at least one of ``cpus``.
+    - ``masks``: one bitmask per physical core: bit ``n`` set when CPU ``n`` is one of
+      its hardware threads.
+    - Returns: the number of cores holding at least one of ``cpus``.
     """
     wanted = sum(1 << cpu for cpu in cpus)
     return sum(1 for mask in masks if mask & wanted)
@@ -118,17 +109,8 @@ def cores_in_masks(masks: Sequence[int], cpus: Sequence[int]) -> int:
 def _linux_cores(cpus: Sequence[int], root: Path) -> int | None:
     """Count the distinct (package, core) pairs of ``cpus`` in a sysfs CPU tree.
 
-    Parameters
-    ----------
-    cpus : sequence of int
-        The CPU indices the process may run on.
-    root : Path
-        The sysfs CPU directory, ``/sys/devices/system/cpu`` on a running system.
-
-    Returns
-    -------
-    int or None
-        The number of physical cores, or ``None`` if any CPU's topology is unreadable.
+    - Returns: the number of physical cores, or ``None`` if any CPU's topology is
+      unreadable.
     """
     pairs: set[tuple[str, str]] = set()
     for cpu in cpus:
@@ -148,15 +130,7 @@ def _linux_cores(cpus: Sequence[int], root: Path) -> int | None:
 def _windows_cores(cpus: Sequence[int]) -> int | None:  # pragma: no cover - Windows
     """Count the physical cores holding ``cpus`` from Windows' processor table.
 
-    Parameters
-    ----------
-    cpus : sequence of int
-        The CPU indices the process may run on (processor group 0).
-
-    Returns
-    -------
-    int or None
-        The number of physical cores, or ``None`` if the table cannot be read.
+    - Returns: the number of physical cores, or ``None`` if the table cannot be read.
     """
     import ctypes
 
@@ -198,18 +172,8 @@ def physical_cores(
     reads each CPU's package and core from ``root``; Windows asks the kernel. macOS on
     Apple silicon has one thread per core, so the CPUs are the cores.
 
-    Parameters
-    ----------
-    cpus : sequence of int
-        The CPU indices the process may run on.
-    root : Path, optional
-        The sysfs CPU directory, read on Linux.
-
-    Returns
-    -------
-    int or None
-        The number of physical cores, or ``None`` on other platforms or when the
-        topology cannot be read.
+    - Returns: the number of physical cores, or ``None`` on other platforms or when the
+      topology cannot be read.
     """
     if sys.platform.startswith("linux"):
         return _linux_cores(cpus, root)

native/src/solprop_native/_counters.py

@@ -151,19 +151,11 @@ def march(
     ) -> None:
         """Count one native march call from its returned rows.
 
-        Parameters
-        ----------
-        kind : str
-            The march, ``adams_march`` or ``rk_march``.
-        reason : str
-            The call's ``march::Reason``, by name.
-        rows : numpy.ndarray
-            The call's attempt rows, the accepted flag in column 3.
-        due : dict
-            Accepted steps from the call's start to each piece of the driver's work,
-            by name, as the call's ``host_step`` bound was formed.
-        read_at : float or None
-            The transverse edge's next read, if the call was bounded by one.
+        - ``kind``: the march, ``adams_march`` or ``rk_march``.
+        - ``rows``: the call's attempt rows, the accepted flag in column 3.
+        - ``due``: accepted steps from the call's start to each piece of the driver's
+          work, by name, as the call's ``host_step`` bound was formed.
+        - ``read_at``: the transverse edge's next read, if the call was bounded by one.
         """
         accepted = int(np.count_nonzero(rows[:, 3])) if rows.size else 0
         self.march_calls[kind] += 1
@@ -191,25 +183,8 @@ def session_batch(
     ) -> None:
         """Count one batch a native session returned from ``advance``.
 
-        Parameters
-        ----------
-        event : str
-            Its event's kind: ``observation``, ``snapshot``, ``warning``,
-            ``terminal``, or ``progress:`` and its cause.
-        attempts : int
-            The attempts its chunk carries.
-        accepted : int
-            The accepted steps among them.
-        rows : int, optional
-            The periodic rows its chunk carries.
-        evaluations : int, optional
-            The statistics evaluations it carries: its rows and its plane statistics.
-        plane : bool, optional
-            Whether it is an observation after the launch.
-        march : str, optional
-            The session's march, for its native march calls.
-        calls : int, optional
-            The native march calls the ``advance`` made.
+        - ``event``: its event's kind: ``observation``, ``snapshot``, ``warning``,
+          ``terminal``, or ``progress:`` and its cause.
         """
         self.returns[f"session_{event}"] += 1
         self.march_attempts += attempts