docstring updates after A5rocks review

Author: jakkdl

src/trio/_core/_parking_lot.py

@@ -92,19 +92,15 @@
 
 
 def add_parking_lot_breaker(task: Task, lot: ParkingLot) -> None:
-    """Register a task as a breaker for a lot. If this task exits without being removed
-    as a breaker, the lot will break. This will cause an error to be raised for all
-    tasks currently parked in the lot, as well as any future tasks that attempt to
-    park in it.
-    """
+    """Register a task as a breaker for a lot. See :meth:`ParkingLot.break_lot`"""
     if task not in GLOBAL_PARKING_LOT_BREAKER:
         GLOBAL_PARKING_LOT_BREAKER[task] = [lot]
     else:
         GLOBAL_PARKING_LOT_BREAKER[task].append(lot)
 
 
 def remove_parking_lot_breaker(task: Task, lot: ParkingLot) -> None:
-    """Deregister a task as a breaker for a lot. See :func:`add_parking_lot_breaker`."""
+    """Deregister a task as a breaker for a lot. See :meth:`ParkingLot.break_lot`"""
     try:
         GLOBAL_PARKING_LOT_BREAKER[task].remove(lot)
     except (KeyError, ValueError):
@@ -273,10 +269,14 @@ def repark_all(self, new_lot: ParkingLot) -> None:
         return self.repark(new_lot, count=len(self))
 
     def break_lot(self, task: Task | None = None) -> None:
-        """Break this lot, causing all parked tasks to raise an error, and any
+        """Break this lot, with ``task`` noted as the task that broke it.
+
+        This causes all parked tasks to raise an error, and any
         future tasks attempting to park to error. Unpark & repark become no-ops as the
         parking lot is empty.
-        The error raised contains a reference to the task sent as a parameter.
+
+        The error raised contains a reference to the task sent as a parameter. It is also
+        saved in the ``broken_by`` attribute.
         """
         if task is None:
             task = _core.current_task()

src/trio/_core/_run.py

@@ -1821,6 +1821,7 @@ async def python_wrapper(orig_coro: Awaitable[RetT]) -> RetT:
         return task
 
     def task_exited(self, task: Task, outcome: Outcome[Any]) -> None:
+        # break parking lots associated with the task exiting
         if task in GLOBAL_PARKING_LOT_BREAKER:
             for lot in GLOBAL_PARKING_LOT_BREAKER[task]:
                 lot.break_lot(task)

src/trio/_core/_tests/test_parking_lot.py

@@ -310,7 +310,9 @@ async def return_me_and_park(
         await lot.park()
 
     lot = ParkingLot()
-    with RaisesGroup(Matcher(_core.BrokenResourceError, match="Parking lot broken by")):
+    with RaisesGroup(
+        Matcher(_core.BrokenResourceError, match="^Parking lot broken by"),
+    ):
         async with _core.open_nursery() as nursery:
             task = await nursery.start(return_me_and_park, lot)
             lot.break_lot(task)

src/trio/_sync.py

@@ -8,8 +8,14 @@
 import trio
 
 from . import _core
-from ._core import Abort, ParkingLot, RaiseCancelT, enable_ki_protection
-from ._core._parking_lot import add_parking_lot_breaker, remove_parking_lot_breaker
+from ._core import (
+    Abort,
+    ParkingLot,
+    RaiseCancelT,
+    add_parking_lot_breaker,
+    enable_ki_protection,
+    remove_parking_lot_breaker,
+)
 from ._util import final
 
 if TYPE_CHECKING:
@@ -599,7 +605,7 @@ async def acquire(self) -> None:
                 await self._lot.park()
             except trio.BrokenResourceError:
                 raise trio.BrokenResourceError(
-                    "Owner of this lock exited without releasing: {self._owner}",
+                    f"Owner of this lock exited without releasing: {self._owner}",
                 ) from None
         else:
             await trio.lowlevel.cancel_shielded_checkpoint()

src/trio/_tests/test_sync.py

@@ -593,7 +593,7 @@ async def lock_taker() -> None:
 
 async def test_lock_acquire_unowned_lock() -> None:
     """Test that trying to acquire a lock whose owner has exited raises an error.
-    Partial fix for https://github.com/python-trio/trio/issues/3035
+    see https://github.com/python-trio/trio/issues/3035
     """
     assert not GLOBAL_PARKING_LOT_BREAKER
     lock = trio.Lock()
@@ -608,6 +608,8 @@ async def test_lock_acquire_unowned_lock() -> None:
 
 
 async def test_lock_multiple_acquire() -> None:
+    """Test for error if awaiting on a lock whose owner exits without releasing.
+    see https://github.com/python-trio/trio/issues/3035"""
     assert not GLOBAL_PARKING_LOT_BREAKER
     lock = trio.Lock()
     with RaisesGroup(