[3.15] gh-141004: Document missing descriptor C APIs (GH-159709) (GH-160136)

(cherry picked from commit aed4ad8)

Co-authored-by: Petr Viktorin <encukou@gmail.com>

Author: ZeroIntensity

Doc/c-api/descriptor.rst

@@ -72,38 +72,34 @@ found in the dictionary of type objects.
    methods on a type, and correspond to :class:`types.MethodDescriptorType`
    objects in Python.
 
+.. c:var:: PyTypeObject PyWrapperDescr_Type
 
-.. c:struct:: wrapperbase
+   The type object for wrapper descriptor objects created by
+   :c:func:`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`.
 
-   Describes a slot wrapper used by :c:func:`PyDescr_NewWrapper`.
+   Wrapper descriptors are used internally to expose special methods
+   such as ``__repr__`` or ``__add__``, which are implemented by type slots.
+   The type is exposed in Python as  :class:`types.WrapperDescriptorType`.
 
-   Each ``wrapperbase`` record stores the Python-visible name and metadata for a
-   special method implemented by a type slot, together with the wrapper
-   function used to adapt that slot to Python's calling convention.
 
-.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
+.. `wrapperbase` & `PyWrapperFlag_KEYWORDS` show up in search and index,
+   and link here, but are only referenced in prose:
 
-   Create a new wrapper descriptor for extension type *type* from the
-   :c:struct:`wrapperbase` structure *base* and the wrapped slot function
-   pointer
-   *wrapped*.
+.. c:struct:: wrapperbase
+   :no-typesetting:
 
-   Wrapper descriptors expose special methods implemented by type slots. This
-   is the same kind of descriptor that CPython creates for slot-based special
-   methods such as ``__repr__`` or ``__add__``, and it appears in Python as a
-   :class:`types.WrapperDescriptorType` object.
+.. c:macro:: PyWrapperFlag_KEYWORDS
+   :no-typesetting:
 
-   On success, return a :term:`strong reference` to the descriptor. Return
-   ``NULL`` with an exception set on failure.
+.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
 
-.. c:var:: PyTypeObject PyWrapperDescr_Type
+   Create a new wrapper descriptor of type :c:var:`PyWrapperDescr_Type`.
 
-   The type object for wrapper descriptor objects created by
-   :c:func:`PyDescr_NewWrapper` and :c:func:`PyWrapper_New`. Wrapper
-   descriptors are used internally to expose special methods implemented
-   via wrapper structures, and appear in Python as
-   :class:`types.WrapperDescriptorType` objects.
+   This function is meant for internal use only; it and
+   related API (``struct wrapperbase`` and the ``PyWrapperFlag_KEYWORDS``
+   flag) are exposed publicly for backwards compatibility reasons.
 
+   See :c:func:`PyCMethod_New` for wrapping a C function.
 
 .. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
 
@@ -138,6 +134,30 @@ found in the dictionary of type objects.
    On success, return a :term:`strong reference` to the wrapper object. Return
    ``NULL`` with an exception set on failure.
 
+.. c:macro:: PyDescr_TYPE(descr)
+
+   Return a :term:`borrowed reference` to the type that the descriptor
+   *descr* belongs to. This is accessible as :attr:`~object.__objclass__`
+   in Python.
+
+   *descr* must be a descriptor object created by one of the
+   ``PyDescr_New*`` functions (an instance of
+   :c:var:`PyMethodDescr_Type`, :c:var:`PyClassMethodDescr_Type`,
+   :c:var:`PyMemberDescr_Type`, :c:var:`PyGetSetDescr_Type`, or
+   :c:var:`PyWrapperDescr_Type`). If the passed descriptor is not
+   an instance of one of these types, the behavior is undefined.
+
+
+.. c:macro:: PyDescr_NAME(descr)
+
+   Return the name of the descriptor *descr* as a :term:`borrowed reference`
+   to a :class:`str` object. This is available as :attr:`~definition.__name__`
+   in Python.
+
+   *descr* must be a descriptor object created by one of the ``PyDescr_New*``
+   functions. If not, the behavior is undefined.
+
+
 .. c:macro:: PyDescr_COMMON
 
    This is a macro including the common fields for a

Tools/check-c-api-docs/ignored_c_api.txt

@@ -1,7 +1,3 @@
-# cpython/descrobject.h
-PyDescr_NAME
-PyDescr_TYPE
-PyWrapperFlag_KEYWORDS
 # Deprecated and removed in 3.16; will not be documented on older versions
 Py_FileSystemDefaultEncodeErrors
 Py_FileSystemDefaultEncoding