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

4 files changed, 17 insertions, 15 deletions

diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index d3bbee23f5..eccb8a67e8 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
 
diff --git a/Doc/library/audit_events.rst b/Doc/library/audit_events.rst
index c23b9c6183..3c68a1515b 100644
--- a/Doc/library/audit_events.rst
+++ b/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.
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 4b0bcde4a8..2f33445a6f 100644
--- a/Doc/library/sys.rst
+++ b/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.
diff --git a/Misc/NEWS.d/next/Core and Builtins/2019-11-22-22-18-50.bpo-38892.LS586s.rst b/Misc/NEWS.d/next/Core and Builtins/2019-11-22-22-18-50.bpo-38892.LS586s.rst
new file mode 100644
index 0000000000..5df67dcbfe
--- /dev/null
+++ b/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.