From beb46970351397f15d77a033452644835848b9ba Mon Sep 17 00:00:00 2001
From: GreedyC <62262441+GreedyC@users.noreply.github.com>
Date: Sat, 17 Oct 2026 10:48:02 +0300
Subject: [PATCH] Document tasks recorded in ParkingLot.broken_by

---
 docs/source/conf.py                | 1 -
 docs/source/reference-lowlevel.rst | 1 +
 newsfragments/3221.doc.rst         | 2 ++
 src/trio/_core/_parking_lot.py     | 8 ++++++++
 4 files changed, 11 insertions(+), 1 deletion(-)
 create mode 100644 newsfragments/3221.doc.rst

diff --git a/docs/source/conf.py b/docs/source/conf.py
index eb278bf65..c9484de41 100755
--- a/docs/source/conf.py
+++ b/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",
 }
 
 
diff --git a/docs/source/reference-lowlevel.rst b/docs/source/reference-lowlevel.rst
index 077f21cd2..d2da0ae05 100644
--- a/docs/source/reference-lowlevel.rst
+++ b/docs/source/reference-lowlevel.rst
@@ -482,6 +482,7 @@ Wait queue abstraction
 .. autoclass:: ParkingLot
    :members:
    :undoc-members:
+   :exclude-members: broken_by
 
 .. autoclass:: ParkingLotStatistics
    :members:
diff --git a/newsfragments/3221.doc.rst b/newsfragments/3221.doc.rst
new file mode 100644
index 000000000..2548448df
--- /dev/null
+++ b/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.
diff --git a/src/trio/_core/_parking_lot.py b/src/trio/_core/_parking_lot.py
index ddf627611..47af7e338 100644
--- a/src/trio/_core/_parking_lot.py
+++ b/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