[clang] [Clang][doc] -ffp-contract options and standard compliance (PR #127621)

[Sjoerd Meijer via cfe-commits]

https://github.com/sjoerdmeijer updated https://github.com/llvm/llvm-project/pull/127621

>From d7483fc138c0834fbed84bb43521ce8caed84528 Mon Sep 17 00:00:00 2001
From: Sjoerd Meijer <smeijer at nvidia.com>
Date: Tue, 18 Feb 2025 03:37:08 -0800
Subject: [PATCH] [Clang][doc] -ffp-contract options and standard compliance

We had an internal discussion about -ffp-contract, how it compared to
GCC which defaults to fast, and standard compliance. Looking at our
docs, I think most information is there, but also thought it could be a
little bit more explicit about when it is and isn't standard compliant.
Let me know if you think this is an improvement or not; happy to abandon
this if you think it is not helping much.
---
 clang/docs/UsersManual.rst | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index d977868b8a2c6..dbbc717fab1c5 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1681,19 +1681,27 @@ for more details.
    permitted to produce more precise results than performing the same
    operations separately.
 
-   The C standard permits intermediate floating-point results within an
+   The C/C++ standard permits intermediate floating-point results within an
    expression to be computed with more precision than their type would
    normally allow. This permits operation fusing, and Clang takes advantage
-   of this by default. This behavior can be controlled with the ``FP_CONTRACT``
-   and ``clang fp contract`` pragmas. Please refer to the pragma documentation
-   for a description of how the pragmas interact with this option.
+   of this by default (``on``). Fusion across statements is not compliant with
+   the C/C++ standard but can be enabled using ``-ffp-contract=fast``.
+
+   Fusion can be controlled with the ``FP_CONTRACT`` and ``clang fp contract``
+   pragmas. Please note that pragmas will be ingored with
+   ``-ffp-contract=fast``, and refer to the pragma documentation for a
+   description of how the pragmas interact with the different ``-ffp-contract``
+   option values.
 
    Valid values are:
 
-   * ``fast`` (fuse across statements disregarding pragmas, default for CUDA)
-   * ``on`` (fuse in the same statement unless dictated by pragmas, default for languages other than CUDA/HIP)
-   * ``off`` (never fuse)
-   * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP)
+   * ``fast``: enable fusion across statements disregarding pragmas, breaking
+     compliance with the C/C++ standard (default for CUDA).
+   * ``on``: enable C/C++ standard complaint fusion in the same statement unless
+     dictated by pragmas (default for languages other than CUDA/HIP)
+   * ``off``: disable fusion
+   * ``fast-honor-pragmas``: fuse across statements unless dictated by pragmas
+     (default for HIP)
 
 .. option:: -f[no-]honor-infinities