[3.12] gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst (GH-114825) (GH-115308)

miss-islington · smontanaro · web-flow · commit 67688609d21c · 2024-02-11T19:02:21.000Z
(cherry picked from commit e1552fd) Co-authored-by: Skip Montanaro <skip.montanaro@gmail.com>
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
@@ -383,7 +383,7 @@ an error value).
 .. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
 
    Function similar to :c:func:`PyErr_WarnFormat`, but *category* is
-   :exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`.
+   :exc:`ResourceWarning` and it passes *source* to :class:`!warnings.WarningMessage`.
 
    .. versionadded:: 3.6
 
@@ -719,7 +719,7 @@ Exception Classes
    This creates a class object derived from :exc:`Exception` (accessible in C as
    :c:data:`PyExc_Exception`).
 
-   The :attr:`__module__` attribute of the new class is set to the first part (up
+   The :attr:`!__module__` attribute of the new class is set to the first part (up
    to the last dot) of the *name* argument, and the class name is set to the last
    part (after the last dot).  The *base* argument can be used to specify alternate
    base classes; it can either be only one class or a tuple of classes. The *dict*
@@ -891,8 +891,8 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
 
    Marks a point where a recursive C-level call is about to be performed.
 
-   If :c:macro:`USE_STACKCHECK` is defined, this function checks if the OS
-   stack overflowed using :c:func:`PyOS_CheckStack`.  In this is the case, it
+   If :c:macro:`!USE_STACKCHECK` is defined, this function checks if the OS
+   stack overflowed using :c:func:`PyOS_CheckStack`.  If this is the case, it
    sets a :exc:`MemoryError` and returns a nonzero value.
 
    The function then checks if the recursion limit is reached.  If this is the
@@ -1145,11 +1145,11 @@ These are compatibility aliases to :c:data:`PyExc_OSError`:
 +-------------------------------------+----------+
 | C Name                              | Notes    |
 +=====================================+==========+
-| :c:data:`PyExc_EnvironmentError`    |          |
+| :c:data:`!PyExc_EnvironmentError`   |          |
 +-------------------------------------+----------+
-| :c:data:`PyExc_IOError`             |          |
+| :c:data:`!PyExc_IOError`            |          |
 +-------------------------------------+----------+
-| :c:data:`PyExc_WindowsError`        | [2]_     |
+| :c:data:`!PyExc_WindowsError`       | [2]_     |
 +-------------------------------------+----------+
 
 .. versionchanged:: 3.3
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
@@ -5,6 +5,7 @@
 Operating System Utilities
 ==========================
 
+
 .. c:function:: PyObject* PyOS_FSPath(PyObject *path)
 
    Return the file system representation for *path*. If the object is a
@@ -97,27 +98,30 @@ Operating System Utilities
 
 .. c:function:: int PyOS_CheckStack()
 
+   .. index:: single: USE_STACKCHECK (C macro)
+
    Return true when the interpreter runs out of stack space.  This is a reliable
-   check, but is only available when :c:macro:`USE_STACKCHECK` is defined (currently
+   check, but is only available when :c:macro:`!USE_STACKCHECK` is defined (currently
    on certain versions of Windows using the Microsoft Visual C++ compiler).
-   :c:macro:`USE_STACKCHECK` will be defined automatically; you should never
+   :c:macro:`!USE_STACKCHECK` will be defined automatically; you should never
    change the definition in your own code.
 
 
+.. c:type::  void (*PyOS_sighandler_t)(int)
+
+
 .. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
 
    Return the current signal handler for signal *i*.  This is a thin wrapper around
    either :c:func:`!sigaction` or :c:func:`!signal`.  Do not call those functions
-   directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void
-   (\*)(int)`.
+   directly!
 
 
 .. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
 
    Set the signal handler for signal *i* to be *h*; return the old signal handler.
    This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`.  Do
-   not call those functions directly!  :c:type:`PyOS_sighandler_t` is a typedef
-   alias for :c:expr:`void (\*)(int)`.
+   not call those functions directly!
 
 .. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
 
@@ -380,10 +384,8 @@ accessible to C code.  They all work with the current interpreter thread's
    silently abort the operation by raising an error subclassed from
    :class:`Exception` (other errors will not be silenced).
 
-   The hook function is of type :c:expr:`int (*)(const char *event, PyObject
-   *args, void *userData)`, where *args* is guaranteed to be a
-   :c:type:`PyTupleObject`. The hook function is always called with the GIL
-   held by the Python interpreter that raised the event.
+   The hook function is always called with the GIL held by the Python
+   interpreter that raised the event.
 
    See :pep:`578` for a detailed description of auditing.  Functions in the
    runtime and standard library that raise events are listed in the
@@ -392,12 +394,20 @@ accessible to C code.  They all work with the current interpreter thread's
 
    .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook
 
-      If the interpreter is initialized, this function raises a auditing event
+      If the interpreter is initialized, this function raises 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 is cleared. As a result, callers cannot assume
       that their hook has been added unless they control all existing hooks.
 
+   .. c:namespace:: NULL
+   .. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData)
+
+      The type of the hook function.
+      *event* is the C string event argument passed to :c:func:`PySys_Audit`.
+      *args* is guaranteed to be a :c:type:`PyTupleObject`.
+      *userData* is the argument passed to PySys_AddAuditHook().
+
    .. versionadded:: 3.8
 
 
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
@@ -4,7 +4,6 @@
 
 Doc/c-api/arg.rst
 Doc/c-api/descriptor.rst
-Doc/c-api/exceptions.rst
 Doc/c-api/float.rst
 Doc/c-api/gcsupport.rst
 Doc/c-api/init.rst
@@ -13,7 +12,6 @@ Doc/c-api/intro.rst
 Doc/c-api/module.rst
 Doc/c-api/object.rst
 Doc/c-api/stable.rst
-Doc/c-api/sys.rst
 Doc/c-api/type.rst
 Doc/c-api/typeobj.rst
 Doc/extending/extending.rst
