Issue #29282: add fused multiply-add function, math.fma.

1 files changed, 15 insertions, 0 deletions

diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index da2b8cc586..42bbb02d92 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -57,6 +57,21 @@ Number-theoretic and representation functions
    If *x* is not a float, delegates to ``x.__floor__()``, which should return an
    :class:`~numbers.Integral` value.
 
+.. function:: fma(x, y, z)
+
+   Fused multiply-add operation. Return ``(x * y) + z``, computed as though with
+   infinite precision and range followed by a single round to the ``float``
+   format. This operation often provides better accuracy than the direct
+   expression ``(x * y) + z``.
+
+   This function follows the specification of the fusedMultiplyAdd operation
+   described in the IEEE 754-2008 standard. The standard leaves one case
+   implementation-defined, namely the result of ``fma(0, inf, nan)``
+   and ``fma(inf, 0, nan)``. In these cases, ``math.fma`` returns a NaN,
+   and does not raise any exception.
+
+   .. versionadded:: 3.7
+
 
 .. function:: fmod(x, y)