gh-141004: Document `PyException_HEAD` and `PyDescr_COMMON` (GH-143896)

diff --git a/Doc/c-api/descriptor.rst b/Doc/c-api/descriptor.rst
index 313c534545a8614321dcacf66a3588a8d9aede93..e23288c6a58590013cdb368fe4e3f51c98e34555 100644 (file)
--- a/Doc/c-api/descriptor.rst
+++ b/Doc/c-api/descriptor.rst
@@ -10,11 +10,6 @@ found in the dictionary of type objects.
 
 .. XXX document these!
 
-.. c:var:: PyTypeObject PyProperty_Type
-
-   The type object for the built-in descriptor types.
-
-
 .. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
 
 
@@ -74,9 +69,26 @@ found in the dictionary of type objects.
 .. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
 
 
+.. c:macro:: PyDescr_COMMON
+
+   This is a :term:`soft deprecated` macro including the common fields for a
+   descriptor object.
+
+   This was included in Python's C API by mistake; do not use it in extensions.
+   For creating custom descriptor objects, create a class implementing the
+   descriptor protocol (:c:member:`~PyTypeObject.tp_descr_get` and
+   :c:member:`~PyTypeObject.tp_descr_set`).
+
+
 Built-in descriptors
 ^^^^^^^^^^^^^^^^^^^^
 
+.. c:var:: PyTypeObject PyProperty_Type
+
+   The type object for property objects. This is the same object as
+   :class:`property` in the Python layer.
+
+
 .. c:var:: PyTypeObject PySuper_Type
 
    The type object for super objects. This is the same object as

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index d7fe9e2c9ec9b49bdf557655282904cb9da607be..59af470f59ff345df93d1209587e3eea4e18e266 100644 (file)
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -793,6 +793,17 @@ Exception Classes
    Return :c:member:`~PyTypeObject.tp_name` of the exception class *ob*.
 
 
+.. c:macro:: PyException_HEAD
+
+   This is a :term:`soft deprecated` macro including the base fields for an
+   exception object.
+
+   This was included in Python's C API by mistake and is not designed for use
+   in extensions. For creating custom exception objects, use
+   :c:func:`PyErr_NewException` or otherwise create a class inheriting from
+   :c:data:`PyExc_BaseException`.
+
+
 Exception Objects
 =================
 

diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt
index de78f6425803cb8f544157d2d65f07b7f62cb9f2..e0b2670808c79c2c19178b6274e678cbdd0f5835 100644 (file)
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -66,7 +66,6 @@ PyCF_MASK
 PyCF_MASK_OBSOLETE
 PyCF_SOURCE_IS_UTF8
 # cpython/descrobject.h
-PyDescr_COMMON
 PyDescr_NAME
 PyDescr_TYPE
 PyWrapperFlag_KEYWORDS
@@ -76,8 +75,6 @@ Py_UniversalNewlineFgets
 PyUnstable_CopyPerfMapFile
 PyUnstable_PerfTrampoline_CompileCode
 PyUnstable_PerfTrampoline_SetPersistAfterFork
-# cpython/pyerrors.h
-PyException_HEAD
 # cpython/pyframe.h
 PyUnstable_EXECUTABLE_KINDS
 PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION
@@ -121,4 +118,4 @@ PY_MONITORING_EVENT_BRANCH
 PY_DEF_EVENT
 PY_FOREACH_DICT_EVENT
 # cpython/pystats.h
-PYSTATS_MAX_UOP_ID
\ No newline at end of file
+PYSTATS_MAX_UOP_ID