bpo-37194: Complete PyObject_CallXXX() docs (GH-14156)

Mention explicitly that PyObject_CallXXX() functions raise an
exception an failure.

1 files changed, 16 insertions, 8 deletions

diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index aecd001..e4787ad 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -257,7 +257,7 @@ Object Protocol
 
    Call a callable Python object *callable* without any arguments.
 
-   Returns the result of the call on success, or raise an exception and return
+   Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
    .. versionadded:: 3.9
@@ -271,7 +271,8 @@ Object Protocol
    *args* must not be *NULL*, use an empty tuple if no arguments are needed.
    If no named arguments are needed, *kwargs* can be *NULL*.
 
-   Returns the result of the call on success, or *NULL* on failure.
+   Return the result of the call on success, or raise an exception and return
+   *NULL* on failure.
 
    This is the equivalent of the Python expression:
    ``callable(*args, **kwargs)``.
@@ -282,7 +283,8 @@ Object Protocol
    Call a callable Python object *callable*, with arguments given by the
    tuple *args*.  If no arguments are needed, then *args* can be *NULL*.
 
-   Returns the result of the call on success, or *NULL* on failure.
+   Return the result of the call on success, or raise an exception and return
+   *NULL* on failure.
 
    This is the equivalent of the Python expression: ``callable(*args)``.
 
@@ -293,7 +295,8 @@ Object Protocol
    The C arguments are described using a :c:func:`Py_BuildValue` style format
    string.  The format can be *NULL*, indicating that no arguments are provided.
 
-   Returns the result of the call on success, or *NULL* on failure.
+   Return the result of the call on success, or raise an exception and return
+   *NULL* on failure.
 
    This is the equivalent of the Python expression: ``callable(*args)``.
 
@@ -312,7 +315,8 @@ Object Protocol
 
    The format can be *NULL*, indicating that no arguments are provided.
 
-   Returns the result of the call on success, or *NULL* on failure.
+   Return the result of the call on success, or raise an exception and return
+   *NULL* on failure.
 
    This is the equivalent of the Python expression:
    ``obj.name(arg1, arg2, ...)``.
@@ -330,7 +334,8 @@ Object Protocol
    :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
    of parameters followed by *NULL*.
 
-   Returns the result of the call on success, or *NULL* on failure.
+   Return the result of the call on success, or raise an exception and return
+   *NULL* on failure.
 
    This is the equivalent of the Python expression:
    ``callable(arg1, arg2, ...)``.
@@ -341,7 +346,9 @@ Object Protocol
    Calls a method of the Python object *obj*, where the name of the method is given as a
    Python string object in *name*.  It is called with a variable number of
    :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
-   of parameters followed by *NULL*. Returns the result of the call on success, or
+   of parameters followed by *NULL*.
+
+   Return the result of the call on success, or raise an exception and return
    *NULL* on failure.
 
 
@@ -365,7 +372,8 @@ Object Protocol
    *kwnames* must contain only objects of type ``str`` (not a subclass),
    and all keys must be unique.
 
-   Return the result of the call on success, or *NULL* on failure.
+   Return the result of the call on success, or raise an exception and return
+   *NULL* on failure.
 
    This uses the vectorcall protocol if the callable supports it;
    otherwise, the arguments are converted to use