Document tasks recorded in ParkingLot.broken_by

docs/source/conf.py

@@ -174,7 +174,6 @@ def autodoc_process_signature(
 logger = getLogger("trio")
 UNDOCUMENTED = {
     "trio._subprocess.HasFileno.fileno",
-    "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,2 @@
+Document :attr:`trio.lowlevel.ParkingLot.broken_by`, including how repeated
+calls to :meth:`~trio.lowlevel.ParkingLot.break_lot` record tasks.

src/trio/_core/_parking_lot.py

@@ -146,6 +146,14 @@ class ParkingLot:
     the number of parked tasks, and ``if parking_lot: ...`` to check whether
     there are any parked tasks.
 
+    Attributes:
+        broken_by (list[trio.lowlevel.Task]):
+            Tasks recorded by calls to :meth:`break_lot`, in call order.
+            This list is empty until the lot is broken. Each call appends its
+            ``task`` argument, or the current task if none is supplied, even
+            if the lot is already broken. The same task can therefore appear
+            more than once.
+
     """
 
     # {task: None}, we just want a deque where we can quickly delete random