bpo-38434: Fixes some audit event documentation (GH-16932)
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 @@
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 @@
native function is preferred when possible.
See the :ref:`audit events table <audit-events>` for all events raised by
- ``CPython``.
+ CPython.
.. versionadded:: 3.8