[3.15] gh-116750: Document 3.14 changes around sys.monitoring.clear_tool_id (GH-156706) (#157482)

Co-authored-by: Christian Neumüller <christian+github@neumueller.me>
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>

Author: 3 people

Doc/library/sys.monitoring.rst

@@ -54,11 +54,18 @@ Registering and using tools
 
    Unregister all events and callback functions associated with *tool_id*.
 
+   .. versionadded:: 3.14
+
 .. function:: free_tool_id(tool_id: int, /) -> None
 
    Should be called once a tool no longer requires *tool_id*.
    Will call :func:`clear_tool_id` before releasing *tool_id*.
 
+   .. versionchanged:: 3.14
+      Now calls :func:`clear_tool_id` before releasing *tool_id*.
+      Previously, it would not disable global or local events associated
+      with *tool_id*, nor unregister any callback functions.
+
 .. function:: get_tool(tool_id: int, /) -> str | None
 
    Returns the name of the tool if *tool_id* is in use,

Doc/whatsnew/3.14.rst

@@ -1906,6 +1906,12 @@ sys.monitoring
   These replace and deprecate the :monitoring-event:`!BRANCH` event.
   (Contributed by Mark Shannon in :gh:`122548`.)
 
+* Add :func:`sys.monitoring.clear_tool_id` to unregister all events and
+  callback functions associated with a tool identifier.
+  :func:`sys.monitoring.free_tool_id` now calls it before releasing the
+  tool identifier, instead of leaving its events and callbacks registered.
+  (Contributed by Tian Gao in :gh:`116750`.)
+
 
 sysconfig
 ---------