PEP 669: nitpicks & clarifications (#2767)

pep-0669.rst

@@ -162,16 +162,18 @@ Register callback functions
 
 To register a callable for events call::
 
-  sys.monitoring.register_callback(tool_id:int, event: Event, func: Callable | None)
+  sys.monitoring.register_callback(tool_id:int, event: Event, func: Callable | None) -> Callable | None
 
-``register_callback`` returns the previously registered callback, or ``None``.
+If another callback was registered for the given ``tool_id`` and ``event``,
+it is unregistered and returned.
+Otherwise ``register_callback`` returns ``None``.
 
 Functions can be unregistered by calling
 ``sys.monitoring.register_callback(tool_id, event, None)``.
 
 Callback functions can be registered and unregistered at any time.
 
-Registering a callback function will generate a ``sys.audit`` event.
+Registering or unregistering a callback function will generate a ``sys.audit`` event.
 
 Callback function arguments
 '''''''''''''''''''''''''''
@@ -211,15 +213,12 @@ Different events will provide the callback function with different arguments, as
 
     ``func(code: CodeType, instruction_offset: int) -> DISABLE | Any``
 
-If a callback returns ``sys.monitoring.DISABLE`` then that tool will not
-recieve any more events for that ``(code, instruction_offset)``.
-
+If a callback function returns ``DISABLE``, then that function will no longer
+be called for that ``(code, instruction_offset)`` until
+``sys.monitoring.restart_events()`` is called.
 This feature is provided for coverage and other tools that are only interested
 seeing an event once. 
 
-If a callback function returns ``DISABLE``, then that function will no longer
-be called for that event and location until
-``sys.monitoring.restart_events()`` is called.
 Note that ``sys.monitoring.restart_events()`` is not specific to one tool,
 so tools must be prepared to receive events that they have chosen to DISABLE.
 
@@ -248,12 +247,12 @@ is exceeded.
 Order of events
 ---------------
 
-If an instructions triggers several events the occur in the following order:
+If an instructions triggers several events they occur in the following order:
 
 * MARKER
 * INSTRUCTION
 * LINE
-* All other events (only one of these event can occur per instruction)
+* All other events (only one of these events can occur per instruction)
 
 Each event is delivered to tools in ascending order of ID.
 
@@ -357,7 +356,7 @@ And these operations should be regarded as slow:
 * ``def set_events(tool_id: int, event_set: Event)->None``
 * ``def restart_events()->None``
 
-How slow, the slow operation the operations are, depends on when then happen.
+How slow the slow operations are depends on when then happen.
 If done early in the program, before modules are loaded,
 they should be fairly inexpensive.
 
@@ -460,7 +459,7 @@ Inserting breakpoints
 
 Breakpoints can be inserted by using markers. For example::
 
-  sys.insert_marker(code, offset)
+  sys.monitoring.insert_marker(code, offset)
 
 Which will insert a marker at ``offset`` in ``code``,
 which can be used as a breakpoint.
@@ -470,7 +469,7 @@ should be found from ``code.co_lines()``.
 
 Breakpoints can be removed by removing the marker::
 
-  sys.remove_marker(code, offset)
+  sys.monitoring.remove_marker(code, offset)
 
 Stepping
 ''''''''