bpo-38892: Improve docs for audit event (GH-17361)

(cherry picked from commit e563a155be60fc0757914f87c8138f10de00bb16)

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

1 files changed, 12 insertions, 11 deletions

diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index d3bbee2..eccb8a6 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -309,7 +309,7 @@ accessible to C code.  They all work with the current interpreter thread's
 
 .. c:function:: int PySys_Audit(const char *event, const char *format, ...)
 
-   Raises an auditing event with any active hooks. Returns zero for success
+   Raise an auditing event with any active hooks. Return zero for success
    and non-zero with an exception set on failure.
 
    If any hooks have been added, *format* and other arguments will be used
@@ -327,11 +327,16 @@ accessible to C code.  They all work with the current interpreter thread's
 
 .. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)
 
-   Adds to the collection of active auditing hooks. Returns zero for success
-   and non-zero on failure. If the runtime has been initialized, also sets an
+   Append the callable *hook* to the list of active auditing hooks.
+   Return zero for success
+   and non-zero on failure. If the runtime has been initialized, also set an
    error on failure. Hooks added through this API are called for all
    interpreters created by the runtime.
 
+   The *userData* pointer is passed into the hook function. Since hook
+   functions may be called from different runtimes, this pointer should not
+   refer directly to Python state.
+
    This function is safe to call before :c:func:`Py_Initialize`. When called
    after runtime initialization, existing audit hooks are notified and may
    silently abort the operation by raising an error subclassed from
@@ -342,14 +347,10 @@ accessible to C code.  They all work with the current interpreter thread's
    :c:type:`PyTupleObject`. The hook function is always called with the GIL
    held by the Python interpreter that raised the event.
 
-   The *userData* pointer is passed into the hook function. Since hook
-   functions may be called from different runtimes, this pointer should not
-   refer directly to Python state.
-
-   See :pep:`578` for a detailed description of auditing. Functions in the
-   runtime and standard library that raise events include the details in each
-   function's documentation and listed in the :ref:`audit events table
-   <audit-events>`.
+   See :pep:`578` for a detailed description of auditing.  Functions in the
+   runtime and standard library that raise events are listed in the
+   :ref:`audit events table <audit-events>`.
+   Details are in each function's documentation.
 
    .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook