gh-141004: Document symbol visibility macros (PyAPI_DATA, Py_EXPORTED_SYMBOL, Py_LOCA...

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 5e90d9b7bc91ed33dcd7ed7d1294356461551b08..6886cd85b09a7dc856e1f8e43959ba3a4d00332e 100644 (file)
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -222,6 +222,14 @@ complete listing.
    Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
    be inlined.
 
+.. c:macro:: Py_LOCAL_SYMBOL
+
+   Macro used to declare a symbol as local to the shared library (hidden).
+   On supported platforms, it ensures the symbol is not exported.
+
+   On compatible versions of GCC/Clang, it
+   expands to ``__attribute__((visibility("hidden")))``.
+
 .. c:macro:: Py_MAX(x, y)
 
    Return the maximum value between ``x`` and ``y``.
@@ -376,6 +384,38 @@ complete listing.
       sizeof(array) / sizeof((array)[0])
 
 
+.. c:macro:: Py_EXPORTED_SYMBOL
+
+   Macro used to declare a symbol (function or data) as exported.
+   On Windows, this expands to ``__declspec(dllexport)``.
+   On compatible versions of GCC/Clang, it
+   expands to ``__attribute__((visibility("default")))``.
+   This macro is for defining the C API itself; extension modules should not use it.
+
+
+.. c:macro:: Py_IMPORTED_SYMBOL
+
+   Macro used to declare a symbol as imported.
+   On Windows, this expands to ``__declspec(dllimport)``.
+   This macro is for defining the C API itself; extension modules should not use it.
+
+
+.. c:macro:: PyAPI_FUNC(type)
+
+   Macro used by CPython to declare a function as part of the C API.
+   Its expansion depends on the platform and build configuration.
+   This macro is intended for defining CPython's C API itself;
+   extension modules should not use it for their own symbols.
+
+
+.. c:macro:: PyAPI_DATA(type)
+
+   Macro used by CPython to declare a public global variable as part of the C API.
+   Its expansion depends on the platform and build configuration.
+   This macro is intended for defining CPython's C API itself;
+   extension modules should not use it for their own symbols.
+
+
 .. _api-objects:
 
 Objects, Types and Reference Counts

diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt
index ebc0b5a8710ab57457fafe2f3efefedcba927dcd..096a14a3cc486961165596addf19638a17a56753 100644 (file)
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -18,11 +18,6 @@ Py_HasFileSystemDefaultEncoding
 Py_UTF8Mode
 # pyhash.h
 Py_HASH_EXTERNAL
-# exports.h
-PyAPI_DATA
-Py_EXPORTED_SYMBOL
-Py_IMPORTED_SYMBOL
-Py_LOCAL_SYMBOL
 # modsupport.h
 PyABIInfo_FREETHREADING_AGNOSTIC
 # moduleobject.h