Reorganize and reword the 'Useful macros' section

- Group the macros
- Roughly order them to put the most important ones first
- Add expansions where it makes sense; especially if there's
  an equivalent in modern C or a common compiler

Author: encukou

Doc/c-api/intro.rst

@@ -157,123 +157,37 @@ Others of a more general utility are defined here.  This is not necessarily a
 complete listing.
 
 
+Utilities
+---------
+
 .. c:macro:: Py_ABS(x)
 
    Return the absolute value of ``x``.
+   The argument may be evaluated twice.
 
    If the result cannot be represented (for example, if ``x`` has
    :c:macro:`!INT_MIN` value for :c:expr:`int` type), the behavior is
    undefined.
 
-   .. versionadded:: 3.3
-
-.. c:macro:: Py_ALWAYS_INLINE
-
-   Ask the compiler to always inline a static inline function. The compiler can
-   ignore it and decide to not inline the function.
-
-   It can be used to inline performance critical static inline functions when
-   building Python in debug mode with function inlining disabled. For example,
-   MSC disables function inlining when building in debug mode.
-
-   Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
-   worse performances (due to increased code size for example). The compiler is
-   usually smarter than the developer for the cost/benefit analysis.
-
-   If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
-   macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.
-
-   It must be specified before the function return type. Usage::
-
-       static inline Py_ALWAYS_INLINE int random(void) { return 4; }
-
-   .. versionadded:: 3.11
-
-.. c:macro:: Py_CHARMASK(c)
-
-   Argument must be a character or an integer in the range [-128, 127] or [0,
-   255].  This macro returns ``c`` cast to an ``unsigned char``.
-
-.. c:macro:: Py_DEPRECATED(version)
-
-   Use this for deprecated declarations.  The macro must be placed before the
-   symbol name.
-
-   Example::
-
-      Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
-
-   .. versionchanged:: 3.8
-      MSVC support was added.
-
-.. c:macro:: Py_GETENV(s)
-
-   Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
-   command line (see :c:member:`PyConfig.use_environment`).
-
-.. c:macro:: Py_LOCAL(type)
-
-   Declare a function returning the specified *type* using a fast-calling
-   qualifier for functions that are local to the current file.
-   Semantically, this is equivalent to ``static type``.
-
-.. c:macro:: Py_LOCAL_INLINE(type)
-
-   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``.
+   Corresponds roughly to :samp:`(({x}) < 0 ? -({x}) : ({x}))`
 
    .. versionadded:: 3.3
 
-.. c:macro:: Py_MEMBER_SIZE(type, member)
-
-   Return the size of a structure (``type``) ``member`` in bytes.
-
-   .. versionadded:: 3.6
-
-.. c:macro:: Py_MEMCPY(dest, src, n)
-
-   This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
-   Use :c:func:`!memcpy` directly instead.
-
-   .. deprecated:: 3.14
-      The macro is :term:`soft deprecated`.
+.. c:macro:: Py_MAX(x, y)
+             Py_MIN(x, y)
 
-.. c:macro:: Py_MIN(x, y)
+   Return the larger or smaller of the arguments, respectively.
+   Any arguments may be evaluated twice.
 
-   Return the minimum value between ``x`` and ``y``.
+   :c:macro:`!Py_MAX` corresponds roughly to
+   :samp:`((({x}) > ({y})) ? ({x}) : ({y}))`.
 
    .. versionadded:: 3.3
 
-.. c:macro:: Py_NO_INLINE
-
-   Disable inlining on a function. For example, it reduces the C stack
-   consumption: useful on LTO+PGO builds which heavily inline code (see
-   :issue:`33720`).
-
-   Usage::
-
-       Py_NO_INLINE static int random(void) { return 4; }
-
-   .. versionadded:: 3.11
-
-.. c:macro:: Py_STRINGIFY(x)
-
-   Convert ``x`` to a C string.  E.g. ``Py_STRINGIFY(123)`` returns
-   ``"123"``.
+.. c:macro:: Py_GETENV(s)
 
-   .. versionadded:: 3.4
+   Like :c:expr:`getenv(s)`, but returns ``NULL`` if :option:`-E` was passed on the
+   command line (see :c:member:`PyConfig.use_environment`).
 
 .. c:macro:: Py_UNREACHABLE()
 
@@ -286,8 +200,10 @@ complete listing.
    avoids a warning about unreachable code.  For example, the macro is
    implemented with ``__builtin_unreachable()`` on GCC in release mode.
 
+   In debug mode, the macro compiles to a call to :c:func:`Py_FatalError`.
+
    A use for ``Py_UNREACHABLE()`` is following a call a function that
-   never returns but that is not declared :c:macro:`_Py_NO_RETURN`.
+   never returns but that is not declared ``_Noreturn``.
 
    If a code path is very unlikely code but can be reached under exceptional
    case, this macro must not be used.  For example, under low memory condition
@@ -297,18 +213,34 @@ complete listing.
 
    .. versionadded:: 3.7
 
-.. c:macro:: Py_UNUSED(arg)
+.. c:macro:: Py_MEMBER_SIZE(type, member)
 
-   Use this for unused arguments in a function definition to silence compiler
-   warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
+   Return the size of a structure (*type*) *member* in bytes.
 
-   .. versionadded:: 3.4
+   Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`.
+
+   .. versionadded:: 3.6
+
+.. c:macro:: Py_ARRAY_LENGTH(array)
+
+   Compute the length of a statically allocated C array at compile time.
+
+   The *array* argument must be a C array with a size known at compile time.
+   Passing an array with an unknown size, such as a heap-allocated array,
+   will result in a compilation error on some compilers, or otherwise produce
+   incorrect results.
+
+   This is roughly equivalent to::
+
+      sizeof(array) / sizeof((array)[0])
 
 .. c:macro:: Py_BUILD_ASSERT(cond)
 
    Asserts a compile-time condition *cond*, as a statement.
    The build will fail if the condition is false or cannot be evaluated at compile time.
 
+   Corresponds roughly to :samp:`static_assert({cond})` on C23 and above.
+
    For example::
 
       Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));
@@ -327,13 +259,42 @@ complete listing.
 
    .. versionadded:: 3.3
 
+.. c:macro:: Py_STRINGIFY(x)
+
+   Convert ``x`` to a C string.  For example, ``Py_STRINGIFY(123)`` returns
+   ``"123"``.
+
+   .. versionadded:: 3.4
+
+.. c:macro:: Py_UNUSED(arg)
+
+   Use this for unused arguments in a function definition to silence compiler
+   warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
+
+   .. versionadded:: 3.4
+
+.. c:macro:: Py_CHARMASK(c)
+
+   Argument must be a character or an integer in the range [-128, 127] or [0,
+   255].  This macro returns ``c`` cast to an ``unsigned char``.
+
+.. c:macro:: Py_MEMCPY(dest, src, n)
+
+   This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
+   Use :c:func:`!memcpy` directly instead.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.
+
+
+Docstring utilities
+-------------------
+
 .. c:macro:: PyDoc_STRVAR(name, str)
 
    Creates a variable with name *name* that can be used in docstrings.
-   If Python is built without docstrings, the value will be empty.
-
-   Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
-   Python without docstrings, as specified in :pep:`7`.
+   If Python is built :option:`without docstrings <--without-doc-strings>`,
+   the value will be an empty string.
 
    Example::
 
@@ -345,13 +306,12 @@ complete listing.
           // ...
       }
 
-.. c:macro:: PyDoc_STR(str)
+   Expands to :samp:`PyDoc_VAR({name}) = PyDoc_STR({str})`.
 
-   Creates a docstring for the given input string or an empty string
-   if docstrings are disabled.
+.. c:macro:: PyDoc_STR(str)
 
-   Use :c:macro:`PyDoc_STR` in specifying docstrings to support
-   building Python without docstrings, as specified in :pep:`7`.
+   Expands to the given input string, or an empty string
+   if docstrings are :option:`disabled <--without-doc-strings>`.
 
    Example::
 
@@ -363,26 +323,94 @@ complete listing.
 
 .. c:macro:: PyDoc_VAR(name)
 
-   Declares a static character array variable with the given name *name*.
+   Declares a static character array variable with the given *name*.
+   Expands to :samp:`static const char {name}[]`
 
    For example::
 
-      PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
-                                        "to the tropics and subtropics of the Eastern Hemisphere.");
+      PyDoc_VAR(python_doc) = PyDoc_STR(
+         "A genus of constricting snakes in the Pythonidae family native "
+         "to the tropics and subtropics of the Eastern Hemisphere.");
 
-.. c:macro:: Py_ARRAY_LENGTH(array)
 
-   Compute the length of a statically allocated C array at compile time.
+Declaration utilities
+---------------------
 
-   The *array* argument must be a C array with a size known at compile time.
-   Passing an array with an unknown size, such as a heap-allocated array,
-   will result in a compilation error on some compilers, or otherwise produce
-   incorrect results.
+The following macros can be used in declarations.
+They are most useful for defining the C API itself, and have limited use
+for extension authors.
+Most of them expand to compiler-specific spellings of common extensions
+to the C language.
 
-   This is roughly equivalent to::
+.. c:macro:: Py_ALWAYS_INLINE
 
-      sizeof(array) / sizeof((array)[0])
+   Ask the compiler to always inline a static inline function. The compiler can
+   ignore it and decide to not inline the function.
+
+   Corresponds to ``always_inline`` attribute in GCC and ``__forceinline``
+   in MSVC.
+
+   It can be used to inline performance critical static inline functions when
+   building Python in debug mode with function inlining disabled. For example,
+   MSC disables function inlining when building in debug mode.
+
+   Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
+   worse performances (due to increased code size for example). The compiler is
+   usually smarter than the developer for the cost/benefit analysis.
+
+   If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
+   macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.
+
+   It must be specified before the function return type. Usage::
+
+       static inline Py_ALWAYS_INLINE int random(void) { return 4; }
+
+   .. versionadded:: 3.11
+
+.. c:macro:: Py_NO_INLINE
+
+   Disable inlining on a function. For example, it reduces the C stack
+   consumption: useful on LTO+PGO builds which heavily inline code (see
+   :issue:`33720`).
+
+   Corresponds to the ``noinline`` attribute/specification on GCC and MSVC.
+
+   Usage::
+
+       Py_NO_INLINE static int random(void) { return 4; }
+
+   .. versionadded:: 3.11
 
+.. c:macro:: Py_DEPRECATED(version)
+
+   Use this to declare APIs that were deprecated in a specific CPYthon version.
+   The macro must be placed before the symbol name.
+
+   Example::
+
+      Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
+
+   .. versionchanged:: 3.8
+      MSVC support was added.
+
+.. c:macro:: Py_LOCAL(type)
+
+   Declare a function returning the specified *type* using a fast-calling
+   qualifier for functions that are local to the current file.
+   Semantically, this is equivalent to :samp:`static {type}`.
+
+.. c:macro:: Py_LOCAL_INLINE(type)
+
+   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_EXPORTED_SYMBOL