docs: document HasFileno.fileno and ParkingLot.broken_by (remaining #3221 items)

docs/source/conf.py

@@ -172,8 +172,9 @@ def autodoc_process_signature(
 
 # currently undocumented things
 logger = getLogger("trio")
-UNDOCUMENTED = {
-    "trio._subprocess.HasFileno.fileno",
+# ``ParkingLot.broken_by`` is a slotted attrs field; its documentation lives
+# in the ``ParkingLot`` class docstring's ``Attributes:`` block.
+UNDOCUMENTED: set[str] = {
     "trio.lowlevel.ParkingLot.broken_by",
 }
 

docs/source/reference-lowlevel.rst

@@ -482,6 +482,7 @@ Wait queue abstraction
 .. autoclass:: ParkingLot
    :members:
    :undoc-members:
+   :exclude-members: broken_by
 
 .. autoclass:: ParkingLotStatistics
    :members:

newsfragments/3221.doc.rst

@@ -0,0 +1,3 @@
+Filled in the missing documentation for ``trio._subprocess.HasFileno.fileno``
+and ``trio.lowlevel.ParkingLot.broken_by``, which completes the checklist in
+issue #3221.

src/trio/_core/_parking_lot.py

@@ -146,6 +146,10 @@ class ParkingLot:
     the number of parked tasks, and ``if parking_lot: ...`` to check whether
     there are any parked tasks.
 
+    Attributes:
+        broken_by: The tasks that broke this parking lot, most recent
+            last. See :meth:`break_lot`.
+
     """
 
     # {task: None}, we just want a deque where we can quickly delete random

src/trio/_subprocess.py

@@ -98,7 +98,12 @@ def pidfd_open(fd: int, flags: int) -> int:
 class HasFileno(Protocol):
     """Represents any file-like object that has a file descriptor."""
 
-    def fileno(self) -> int: ...
+    def fileno(self) -> int:
+        """Returns the file descriptor of this file-like object, as an
+        integer. It is passed to the child process, e.g. when a
+        :class:`HasFileno` object is used as ``stdin``, ``stdout`` or
+        ``stderr`` of a spawned process."""
+        ...
 
 
 @final

src/trio/_tests/_check_type_completeness.json

@@ -12,7 +12,6 @@
     "all": [
         "No docstring found for class \"trio._core._run.Task\"",
         "No docstring found for class \"trio._socket.SocketType\"",
-        "No docstring found for function \"trio._subprocess.HasFileno.fileno\"",
         "No docstring found for class \"trio._sync.AsyncContextManagerMixin\"",
         "No docstring found for function \"trio._sync._HasAcquireRelease.acquire\"",
         "No docstring found for function \"trio._sync._HasAcquireRelease.release\"",