Small doc tweaks

docs/source/reference-hazmat.rst

@@ -403,11 +403,11 @@ Low-level blocking
 .. autofunction:: reschedule
 
 Here's an example lock class implemented using
-:func:`wait_task_rescheduled` directly. This implementation has a number
-of flaws, including lack of fairness, O(n) cancellation, missing error
-checking, failure to insert a checkpoint on the non-blocking path,
-etc. If you really want to implement your own lock, then you should
-study the implementation of :class:`trio.Lock` and use
+:func:`wait_task_rescheduled` directly. This implementation has a
+number of flaws, including lack of fairness, O(n) cancellation,
+missing error checking, failure to insert a checkpoint on the
+non-blocking path, etc. If you really want to implement your own lock,
+then you should study the implementation of :class:`trio.Lock` and use
 :class:`ParkingLot`, which handles some of these issues for you. But
 this does serve to illustrate the basic structure of the
 :func:`wait_task_rescheduled` API::

trio/_core/_traps.py

@@ -75,7 +75,8 @@ def wait_task_rescheduled(abort_func):
     """Put the current task to sleep, with cancellation support.
 
     This is the lowest-level API for blocking in trio. Every time a
-    :class:`~trio.hazmat.Task` blocks, it does so by calling this function.
+    :class:`~trio.hazmat.Task` blocks, it does so by calling this function
+    (usually indirectly via some higher-level API).
 
     This is a tricky interface with no guard rails. If you can use
     :class:`ParkingLot` or the built-in I/O wait functions instead, then you