gh-159808: Sync documented C API structs with their headers (GH-159812)

Author: ngoldbaum

Doc/c-api/import.rst

@@ -257,14 +257,11 @@ Importing Modules
    This is the structure type definition for frozen module descriptors, as
    generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
    Python source distribution).  Its definition, found in :file:`Include/import.h`,
-   is::
-
-      struct _frozen {
-          const char *name;
-          const unsigned char *code;
-          int size;
-          bool is_package;
-      };
+   is:
+
+   .. literalinclude:: ../../Include/cpython/import.h
+      :start-at: struct _frozen {
+      :end-at: };
 
    .. versionchanged:: 3.11
       The new ``is_package`` field indicates whether the module is a package or not.

Doc/c-api/slots.rst

@@ -48,7 +48,9 @@ Entries of the slots array use the following structure:
     typedef struct {
         uint16_t sl_id;
         uint16_t sl_flags;
-        uint32_t _reserved;  // must be 0
+        union {
+            uint32_t sl_reserved;  // must be 0
+        };
         union {
             void *sl_ptr;
             void (*sl_func)(void);

Doc/c-api/typeobj.rst

@@ -480,6 +480,7 @@ definition found there:
 .. XXX Drop this?
 
 .. literalinclude:: ../includes/typestruct.h
+   :end-at: } PyTypeObject;
 
 
 PyObject Slots

Doc/extending/newtypes.rst

@@ -15,6 +15,7 @@ Here is the definition of :c:type:`PyTypeObject`, with some fields only used in
 :ref:`debug builds <debug-build>` omitted:
 
 .. literalinclude:: ../includes/typestruct.h
+   :end-at: } PyTypeObject;
 
 
 Now that's a *lot* of methods.  Don't worry too much though -- if you have
@@ -285,7 +286,7 @@ be read-only or read-write.  The structures in the table are defined as::
    typedef struct PyMemberDef {
        const char *name;
        int         type;
-       int         offset;
+       Py_ssize_t  offset;
        int         flags;
        const char *doc;
    } PyMemberDef;

Doc/includes/typestruct.h

@@ -93,3 +93,7 @@ typedef struct _typeobject {
      */
     uint16_t tp_versions_used;
 } PyTypeObject;
+
+/* Private fields are intentionally omitted.
+ * Keep them excluded when updating this definition.
+ */

Include/cpython/import.h

@@ -17,6 +17,8 @@ PyAPI_FUNC(PyObject *) PyImport_CreateModuleFromInitfunc(
     PyObject *spec,
     PyObject *(*initfunc)(void));
 
+/* This structure is included verbatim in the public documentation
+   (Doc/c-api/import.rst). */
 struct _frozen {
     const char *name;                 /* ASCII encoded string */
     const unsigned char *code;