PEP 788: Add clarification to some parts

Author: ZeroIntensity

peps/pep-0788.rst

@@ -348,14 +348,11 @@ way). This generally happens when a thread calls :c:func:`PyEval_RestoreThread`
 or in between bytecode instructions, based on :func:`sys.setswitchinterval`.
 
 A new, internal field will be added to the ``PyThreadState`` structure that
-determines if the thread is daemon. If the thread is daemon, then it will
-hang during attachment as usual, but if it's not, then the interpreter will
-let the thread attach and continue execution. On with-GIL builds, this again
-means handing off the GIL to the thread. During finalization, the interpreter
+determines if the thread is daemon. Before finalization, the interpreter
 will wait until all non-daemon threads call :c:func:`PyThreadState_Delete`.
 
-For backwards compatibility, all thread states created by existing APIs will
-remain daemon by default.
+For backwards compatibility, all thread states created by existing APIs,
+including :c:func:`PyGILState_Ensure`, will remain daemon by default.
 
 .. c:function:: int PyThreadState_SetDaemon(int is_daemon)
 
@@ -396,8 +393,8 @@ A non-zero reference count prevents the interpreter from finalizing.
     This function is generally meant to be used in tandem with
     :c:func:`PyThreadState_Ensure`.
 
-    The caller must have an :term:`attached thread state`, and cannot return
-    ``NULL``. Failures are always a fatal error.
+    The caller must have an :term:`attached thread state`. This function
+    cannot return ``NULL``. Failures are always a fatal error.
 
 .. c:function:: PyInterpreterState *PyInterpreterState_Lookup(int64_t interp_id)
 
@@ -438,7 +435,7 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
     there is a subsequent call to :c:func:`PyThreadState_Release` that matches
     this one.
 
-    The interpreter's *interp* reference count is decremented by one.
+    The reference to the interpreter *interp* is stolen by this function.
     As such, *interp* should have been acquired by
     :c:func:`PyInterpreterState_Hold`.
 
@@ -454,8 +451,9 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
 
 .. c:function:: void PyThreadState_Release()
 
-    Detach and destroy the :term:`attached thread state` set by
-    :c:func:`PyThreadState_Ensure`.
+    Release the :term:`attached thread state` set by
+    :c:func:`PyThreadState_Ensure`. Any thread state that was set prior
+    to the original call to :c:func:`PyThreadState_Ensure` will be restored.
 
     This function cannot fail, but may hang the thread if the
     attached thread state prior to the original :c:func:`!PyThreadState_Ensure`
@@ -728,7 +726,7 @@ deleted and cause use-after-free violations. :c:func:`PyInterpreterState_Hold`
 fixes this issue anyway, but an interpreter ID does have the benefit of
 requiring less magic in the implementation, but has several downsides:
 
--  Nearly all existing APIs already return a :c:type:`PyInterpreterState`
+-  Nearly all existing interpreter APIs already return a :c:type:`PyInterpreterState`
    pointer, not an interpreter ID. Functions like
    :c:func:`PyThreadState_GetInterpreter` would have to be accompanied by
    frustrating calls to :c:func:`PyInterpreterState_GetID`. There's also