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

[via cfe-commits]

Author: Sjoerd Meijer
Date: 2025-02-20T10:10:23Z
New Revision: dc326d0b01f63e49f4f11c0c332369bf109721df

URL: https://github.com/llvm/llvm-project/commit/dc326d0b01f63e49f4f11c0c332369bf109721df
DIFF: https://github.com/llvm/llvm-project/commit/dc326d0b01f63e49f4f11c0c332369bf109721df.diff

LOG: [Clang][doc] -ffp-contract options and standard compliance (#127621)

We had an discussion about -ffp-contract, how it compared to GCC which defaults
to fast, and standard compliance. Looking at our docs, most information is
there, but this clarifies when this option is and isn't standard compliant.

Added: 
    

Modified: 
    clang/docs/UsersManual.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index d977868b8a2c6..8213334b61c22 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 and C++ standards permit 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 and C++ standards 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 
diff erent ``-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 and C++ standards (default for CUDA).
+   * ``on``: enable C and 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