bpo-38434: Fixes some audit event documentation (GH-16932)

5 files changed, 26 insertions, 11 deletions

diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 3c4f669..45a6b4a 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -40,8 +40,6 @@ bound into a function.
    can bind you to a precise Python version since the definition of the bytecode
    changes often.
 
-   .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags c.PyCode_New
-
 .. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
 
    Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positonal-only arguments.
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 838a97c..87d2bd1 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -330,7 +330,16 @@ accessible to C code.  They all work with the current interpreter thread's
 
    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.
+   function's documentation and listed in the :ref:`audit events table
+   <audit-events>`.
+
+   .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook
+
+      If the interpreter is initialized, this function raises a 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 is cleared. As a result, callers cannot assume
+      that their hook has been added unless they control all existing hooks.
 
    .. versionadded:: 3.8
 
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index c6c643b..a2e930b 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -33,18 +33,21 @@ always available.
    tuple of arguments. Native hooks added by :c:func:`PySys_AddAuditHook` are
    called first, followed by hooks added in the current interpreter.
 
-   Calling this function will trigger an event for all existing hooks, and if
-   any raise an exception derived from :class:`Exception`, the add will be
-   silently ignored. As a result, callers cannot assume that their hook has been
-   added unless they control all existing hooks.
+   .. audit-event:: sys.addaudithook "" sys.addaudithook
+
+      Raises a 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
+      all existing hooks.
 
    .. versionadded:: 3.8
 
    .. impl-detail::
 
-      When tracing is enabled, Python hooks are only traced if the callable has
-      a ``__cantrace__`` member that is set to a true value. Otherwise, trace
-      functions will not see the hook.
+      When tracing is enabled (see :func:`settrace`), Python hooks are only
+      traced if the callable has a ``__cantrace__`` member that is set to a
+      true value. Otherwise, trace functions will skip the hook.
 
 
 .. data:: argv
@@ -87,7 +90,7 @@ always available.
    native function is preferred when possible.
 
    See the :ref:`audit events table <audit-events>` for all events raised by
-   ``CPython``.
+   CPython.
 
    .. versionadded:: 3.8
 
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index a21fb44..9393f9e 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -138,6 +138,10 @@ Standard names are defined for the following types:
 
    The type for code objects such as returned by :func:`compile`.
 
+   .. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags CodeType
+
+   Note that the audited arguments may not match the names or positions
+   required by the initializer.
 
 .. data:: CellType
 
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 0a043a9..a8ec0fb 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -839,6 +839,7 @@ the :ref:`relativeimports` section.
 :func:`importlib.import_module` is provided to support applications that
 determine dynamically the modules to be loaded.
 
+.. audit-event:: import module,filename,sys.path,sys.meta_path,sys.path_hooks import
 
 .. _future: