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

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
+   Append the callable *hook* to the list of active auditing hooks.
-   and non-zero on failure. If the runtime has been initialized, also sets an
+   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
+   runtime and standard library that raise events are listed in the
-   function's documentation and listed in the :ref:`audit events table
+   :ref:`audit events table <audit-events>`.
-   <audit-events>`.
+   Details are in each function's documentation.
 
    .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook
 

Doc/library/audit_events.rst

@@ -7,7 +7,7 @@ Audit events table
 
 This table contains all events raised by :func:`sys.audit` or
 :c:func:`PySys_Audit` calls throughout the CPython runtime and the
-standard library.
+standard library.  These calls were added in 3.8.0 or later.
 
 See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for
 information on handling these events.

Doc/library/sys.rst

@@ -25,7 +25,7 @@ always available.
 
 .. function:: addaudithook(hook)
 
-   Adds the callable *hook* to the collection of active auditing hooks for the
+   Append the callable *hook* to the list of active auditing hooks for the
    current interpreter.
 
    When an auditing event is raised through the :func:`sys.audit` function, each
@@ -35,7 +35,7 @@ always available.
 
    .. audit-event:: sys.addaudithook "" sys.addaudithook
 
-      Raises a auditing event ``sys.addaudithook`` with no arguments. If any
+      Raise an auditing event ``sys.addaudithook`` with no arguments. If any
       existing hooks raise an exception derived from :class:`Exception`, the
       new hook will not be added and the exception suppressed. As a result,
       callers cannot assume that their hook has been added unless they control
@@ -74,7 +74,7 @@ always available.
 
    .. index:: single: auditing
 
-   Raises an auditing event with any active hooks. The event name is a string
+   Raise an auditing event with any active hooks. The event name is a string
    identifying the event and its associated schema, which is the number and
    types of arguments. The schema for a given event is considered public and
    stable API and should not be modified between releases.

Misc/NEWS.d/next/Core and Builtins/2019-11-22-22-18-50.bpo-38892.LS586s.rst

@@ -0,0 +1 @@
+Improve documentation for audit events table and functions.