[Python-checkins] Adjust stable ABI internal documentation (GH-96896)

[miss-islington]

https://github.com/python/cpython/commit/bbecca523a55d7fde99e22f2d96236c5d016846a
commit: bbecca523a55d7fde99e22f2d96236c5d016846a
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-10-04T06:15:46-07:00
summary:

Adjust stable ABI internal documentation (GH-96896)


I was perusing this file, and noticed that this part of the documentation is slightly out of date: the `struct` items in this TOML file currently contain `struct_abi_kind` members, which distinguish between the different types of ABI compatibility described in the comment.

I've updated the comment to reflect this.
(cherry picked from commit 6e533088290b909df324615df24286489603989f)

Co-authored-by: William Woodruff <william at yossarian.net>

files:
M Misc/stable_abi.toml

diff --git a/Misc/stable_abi.toml b/Misc/stable_abi.toml
index e34bfcd0b617..50dbb0c7bcff 100644
--- a/Misc/stable_abi.toml
+++ b/Misc/stable_abi.toml
@@ -13,13 +13,8 @@
 # The current format is TOML.
 
 # There are these kinds of top-level "items":
-# - struct: A C struct. Currently this file does not distinguish between:
-#   - opaque structs, which the Limited API only handles via pointers
-#     (so these can change at any time)
-#   - structs where only certain members are part of the stable ABI (e.g.
-#     PyObject)
-#   - structs which must not be changed at all (e.g. PyType_Slot, which is
-#     fully defined and used in arrays)
+# - struct: A C struct. See `struct_abi_kind` for how much of the struct is
+#   exposed.
 # - function: A function that must be kept available (and exported, i.e. not
 #   converted to a macro).
 # - const: A simple value, defined with `#define`.
@@ -42,6 +37,18 @@
 #     of the stable ABI.
 #   - a combination of the above (functions that were called by macros that
 #     were public in the past)
+# - struct_abi_kind: for `struct`, defines how much of the struct is exposed:
+#   - 'full-abi': All of the struct is part of the ABI, including the size
+#     (users may define arrays of these structs).
+#     Typically used for initalization, rather than at runtime.
+#   - 'opaque': No members are part of the ABI, nor is the size. The Limited
+#     API only handles these via pointers. The C definition should be
+#     incomplete (opaque).
+#   - 'members': Only specific members are part of the stable ABI.
+#     The struct's size may change, so it can't be used in arrays.
+#     Do not add new structs of this kind without an extremely good reason.
+# - members: For `struct` with struct_abi_kind = 'members', a list of the
+#   exposed members.
 # - doc: for `feature_macro`, the blurb added in documentation
 # - windows: for `feature_macro`, this macro is defined on Windows.
 #   (This info is used to generate the DLL manifest and needs to be available