gh-101578: Amend exception docs (#102057)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Doc/c-api/exceptions.rst

@@ -438,7 +438,9 @@ Querying the error indicator
 
 .. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
 
- As of 3.12, this function is deprecated. Use :c:func:`PyErr_GetRaisedException` instead.
+ .. deprecated:: 3.12
+
+ Use :c:func:`PyErr_GetRaisedException` instead.
 
  Retrieve the error indicator into three variables whose addresses are passed.
  If the error indicator is not set, set all three variables to ``NULL``. If it is
@@ -447,8 +449,10 @@ Querying the error indicator
 
  .. note::
 
- This function is normally only used by code that needs to catch exceptions or
- by code that needs to save and restore the error indicator temporarily, e.g.::
+ This function is normally only used by legacy code that needs to catch
+ exceptions or save and restore the error indicator temporarily.
+
+ For example::
 
  {
  PyObject *type, *value, *traceback;
@@ -459,15 +463,17 @@ Querying the error indicator
  PyErr_Restore(type, value, traceback);
  }
 
- .. deprecated:: 3.12
-
 
 .. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
 
- As of 3.12, this function is deprecated. Use :c:func:`PyErr_SetRaisedException` instead.
+ .. deprecated:: 3.12
+
+ Use :c:func:`PyErr_SetRaisedException` instead.
 
- Set the error indicator from the three objects. If the error indicator is
- already set, it is cleared first. If the objects are ``NULL``, the error
+ Set the error indicator from the three objects,
+ *type*, *value*, and *traceback*,
+ clearing the existing exception if one is set.
+ If the objects are ``NULL``, the error
  indicator is cleared. Do not pass a ``NULL`` type and non-``NULL`` value or
  traceback. The exception type should be a class. Do not pass an invalid
  exception type or value. (Violating these rules will cause subtle problems
@@ -478,18 +484,17 @@ Querying the error indicator
 
  .. note::
 
- This function is normally only used by code that needs to save and restore the
- error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the current
- error indicator.
-
- .. deprecated:: 3.12
+ This function is normally only used by legacy code that needs to
+ save and restore the error indicator temporarily.
+ Use :c:func:`PyErr_Fetch` to save the current error indicator.
 
 
 .. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
 
- As of 3.12, this function is deprecated.
- Use :c:func:`PyErr_GetRaisedException` instead of :c:func:`PyErr_Fetch` to avoid
- any possible de-normalization.
+ .. deprecated:: 3.12
+
+ Use :c:func:`PyErr_GetRaisedException` instead,
+ to avoid any possible de-normalization.
 
  Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
  can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
@@ -507,8 +512,6 @@ Querying the error indicator
  PyException_SetTraceback(val, tb);
  }
 
- .. deprecated:: 3.12
-
 
 .. c:function:: PyObject* PyErr_GetHandledException(void)
 
@@ -756,14 +759,12 @@ Exception Objects
 
 .. c:function:: PyObject* PyException_GetArgs(PyObject *ex)
 
- Return args of the given exception as a new reference,
- as accessible from Python through :attr:`args`.
+ Return :attr:`~BaseException.args` of exception *ex*.
 
 
 .. c:function:: void PyException_SetArgs(PyObject *ex, PyObject *args)
 
- Set the args of the given exception,
- as accessible from Python through :attr:`args`.
+ Set :attr:`~BaseException.args` of exception *ex* to *args*.
 
 
 .. _unicodeexceptions:

Doc/data/refcounts.dat

@@ -839,6 +839,8 @@ PyEval_EvalFrameEx:int:throwflag::
 PyEval_MergeCompilerFlags:int:::
 PyEval_MergeCompilerFlags:PyCompilerFlags*:cf::
 
+PyException_GetArgs:PyObject*::+1:
+
 PyException_GetCause:PyObject*::+1:
 PyException_GetCause:PyObject*:ex:0: