bpo-38892: Improve docs for audit event (GH-17361)
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 @@
.. 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 @@
.. 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 @@
: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