gh-111178: fix incorrect function signatures in docs (#132395)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 9d551aa997ba1f0521cc1bc95c3efe8c5d4de501..6d2201d02f685dc3f25b9f3b20edddd435cd6b3e 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -703,10 +703,13 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    .. code-block:: c
 
-     static void foo_dealloc(foo_object *self) {
+     static void
+     foo_dealloc(PyObject *op)
+     {
+         foo_object *self = (foo_object *) op;
          PyObject_GC_UnTrack(self);
          Py_CLEAR(self->ref);
-         Py_TYPE(self)->tp_free((PyObject *)self);
+         Py_TYPE(self)->tp_free(self);
      }
 
    Finally, if the type is heap allocated (:c:macro:`Py_TPFLAGS_HEAPTYPE`), the
@@ -717,10 +720,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
    .. code-block:: c
 
-     static void foo_dealloc(foo_object *self) {
-         PyTypeObject *tp = Py_TYPE(self);
+     static void
+     foo_dealloc(PyObject *op)
+     {
+         PyTypeObject *tp = Py_TYPE(op);
          // free references and buffers here
-         tp->tp_free(self);
+         tp->tp_free(op);
          Py_DECREF(tp);
      }
 
@@ -1416,8 +1421,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    :mod:`!_thread` extension module::
 
       static int
-      local_traverse(localobject *self, visitproc visit, void *arg)
+      local_traverse(PyObject *op, visitproc visit, void *arg)
       {
+          localobject *self = (localobject *) op;
           Py_VISIT(self->args);
           Py_VISIT(self->kw);
           Py_VISIT(self->dict);
@@ -1511,8 +1517,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    members to ``NULL``, as in the following example::
 
       static int
-      local_clear(localobject *self)
+      local_clear(PyObject *op)
       {
+          localobject *self = (localobject *) op;
           Py_CLEAR(self->key);
           Py_CLEAR(self->args);
           Py_CLEAR(self->kw);

diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 7f57a3a6aac0ed601bea4f2f7694e1c92e361c08..e3612f3a1875cac358ba526219392a979b45ea6d 100644 (file)
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -70,22 +70,24 @@ object itself needs to be freed here as well.  Here is an example of this
 function::
 
    static void
-   newdatatype_dealloc(newdatatypeobject *obj)
+   newdatatype_dealloc(PyObject *op)
    {
-       free(obj->obj_UnderlyingDatatypePtr);
-       Py_TYPE(obj)->tp_free((PyObject *)obj);
+       newdatatypeobject *self = (newdatatypeobject *) op;
+       free(self->obj_UnderlyingDatatypePtr);
+       Py_TYPE(self)->tp_free(self);
    }
 
 If your type supports garbage collection, the destructor should call
 :c:func:`PyObject_GC_UnTrack` before clearing any member fields::
 
    static void
-   newdatatype_dealloc(newdatatypeobject *obj)
+   newdatatype_dealloc(PyObject *op)
    {
-       PyObject_GC_UnTrack(obj);
-       Py_CLEAR(obj->other_obj);
+       newdatatypeobject *self = (newdatatypeobject *) op;
+       PyObject_GC_UnTrack(op);
+       Py_CLEAR(self->other_obj);
        ...
-       Py_TYPE(obj)->tp_free((PyObject *)obj);
+       Py_TYPE(self)->tp_free(self);
    }
 
 .. index::
@@ -117,17 +119,19 @@ done.  This can be done using the :c:func:`PyErr_Fetch` and
            PyErr_Fetch(&err_type, &err_value, &err_traceback);
 
            cbresult = PyObject_CallNoArgs(self->my_callback);
-           if (cbresult == NULL)
-               PyErr_WriteUnraisable(self->my_callback);
-           else
+           if (cbresult == NULL) {
+              PyErr_WriteUnraisable(self->my_callback);
+           }
+           else {
                Py_DECREF(cbresult);
+           }
 
            /* This restores the saved exception state */
            PyErr_Restore(err_type, err_value, err_traceback);
 
            Py_DECREF(self->my_callback);
        }
-       Py_TYPE(obj)->tp_free((PyObject*)self);
+       Py_TYPE(self)->tp_free(self);
    }
 
 .. note::
@@ -168,10 +172,11 @@ representation of the instance for which it is called.  Here is a simple
 example::
 
    static PyObject *
-   newdatatype_repr(newdatatypeobject *obj)
+   newdatatype_repr(PyObject *op)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
-                                   obj->obj_UnderlyingDatatypePtr->size);
+                                   self->obj_UnderlyingDatatypePtr->size);
    }
 
 If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the interpreter will supply a
@@ -188,10 +193,11 @@ used instead.
 Here is a simple example::
 
    static PyObject *
-   newdatatype_str(newdatatypeobject *obj)
+   newdatatype_str(PyObject *op)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
-                                   obj->obj_UnderlyingDatatypePtr->size);
+                                   self->obj_UnderlyingDatatypePtr->size);
    }
 
 
@@ -329,16 +335,16 @@ method of a class would be called.
 Here is an example::
 
    static PyObject *
-   newdatatype_getattr(newdatatypeobject *obj, char *name)
+   newdatatype_getattr(PyObject *op, char *name)
    {
-       if (strcmp(name, "data") == 0)
-       {
-           return PyLong_FromLong(obj->data);
+       newdatatypeobject *self = (newdatatypeobject *) op;
+       if (strcmp(name, "data") == 0) {
+           return PyLong_FromLong(self->data);
        }
 
        PyErr_Format(PyExc_AttributeError,
                     "'%.100s' object has no attribute '%.400s'",
-                    Py_TYPE(obj)->tp_name, name);
+                    Py_TYPE(self)->tp_name, name);
        return NULL;
    }
 
@@ -349,7 +355,7 @@ example that simply raises an exception; if this were really all you wanted, the
 :c:member:`~PyTypeObject.tp_setattr` handler should be set to ``NULL``. ::
 
    static int
-   newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
+   newdatatype_setattr(PyObject *op, char *name, PyObject *v)
    {
        PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
        return -1;
@@ -379,8 +385,10 @@ Here is a sample implementation, for a datatype that is considered equal if the
 size of an internal pointer is equal::
 
    static PyObject *
-   newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)
+   newdatatype_richcmp(PyObject *lhs, PyObject *rhs, int op)
    {
+       newdatatypeobject *obj1 = (newdatatypeobject *) lhs;
+       newdatatypeobject *obj2 = (newdatatypeobject *) rhs;
        PyObject *result;
        int c, size1, size2;
 
@@ -399,8 +407,7 @@ size of an internal pointer is equal::
        case Py_GE: c = size1 >= size2; break;
        }
        result = c ? Py_True : Py_False;
-       Py_INCREF(result);
-       return result;
+       return Py_NewRef(result);
     }
 
 
@@ -439,12 +446,14 @@ This function, if you choose to provide it, should return a hash number for an
 instance of your data type. Here is a simple example::
 
    static Py_hash_t
-   newdatatype_hash(newdatatypeobject *obj)
+   newdatatype_hash(PyObject *op)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        Py_hash_t result;
-       result = obj->some_size + 32767 * obj->some_number;
-       if (result == -1)
-          result = -2;
+       result = self->some_size + 32767 * self->some_number;
+       if (result == -1) {
+           result = -2;
+       }
        return result;
    }
 
@@ -478,8 +487,9 @@ This function takes three arguments:
 Here is a toy ``tp_call`` implementation::
 
    static PyObject *
-   newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)
+   newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)
    {
+       newdatatypeobject *self = (newdatatypeobject *) op;
        PyObject *result;
        const char *arg1;
        const char *arg2;
@@ -490,7 +500,7 @@ Here is a toy ``tp_call`` implementation::
        }
        result = PyUnicode_FromFormat(
            "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
-           obj->obj_UnderlyingDatatypePtr->size,
+           self->obj_UnderlyingDatatypePtr->size,
            arg1, arg2, arg3);
        return result;
    }
@@ -563,12 +573,12 @@ The only further addition is that ``tp_dealloc`` needs to clear any weak
 references (by calling :c:func:`PyObject_ClearWeakRefs`)::
 
    static void
-   Trivial_dealloc(TrivialObject *self)
+   Trivial_dealloc(PyObject *op)
    {
        /* Clear weakrefs first before calling any destructors */
-       PyObject_ClearWeakRefs((PyObject *) self);
+       PyObject_ClearWeakRefs(op);
        /* ... remainder of destruction code omitted for brevity ... */
-       Py_TYPE(self)->tp_free((PyObject *) self);
+       Py_TYPE(op)->tp_free(op);
    }
 
 

diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index b062e6b4c9bca095394d93dd820b3d041dc8db2f..896e8f4a489649cdbbf55e367af6bcb20402645a 100644 (file)
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -1161,7 +1161,8 @@ Changes in the C API
     .. code-block:: c
 
         int
-        foo_traverse(foo_struct *self, visitproc visit, void *arg) {
+        foo_traverse(PyObject *self, visitproc visit, void *arg)
+        {
         // Rest of the traverse function
         #if PY_VERSION_HEX >= 0x03090000
             // This was not needed before Python 3.9 (Python issue 35810 and 40217)