[flang-commits] [flang] [flang][NFC] Document that the integrity of parentheses is not violated (PR #175071)

[Peter Klausler via flang-commits]

https://github.com/klausler updated https://github.com/llvm/llvm-project/pull/175071

>From 716e2fa73dadee88fe9e73e0e7c2020254b695ff Mon Sep 17 00:00:00 2001
From: Peter Klausler <pklausler at nvidia.com>
Date: Thu, 8 Jan 2026 13:25:45 -0800
Subject: [PATCH] [flang][NFC] Document that the integrity of parentheses is
 not violated

Add language to flang/docs/Extensions.md to explain why "A+(B*C)"
must round the result of the multiplication, when REAL and the
-ffast-math option is not used.
---
 flang/docs/Extensions.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/flang/docs/Extensions.md b/flang/docs/Extensions.md
index c3837ce7ce65a..6f02a51c81492 100644
--- a/flang/docs/Extensions.md
+++ b/flang/docs/Extensions.md
@@ -980,6 +980,27 @@ print *, [(j,j=1,10)]
   are noted only as warnings when they appear in code known to be
   dead anyway at compilation time.
 
+## Behavior in cases where the standard is clear but disputed
+
+* Unless one uses `-ffast-math`, directly or by implication,
+  the parentheses in real expressions like `A+(B*C)` will prevent
+  fusing the multiplication with the addition using an "FMA"
+  operation that only rounds the final result.
+  F'2023 10.1.2.4 paragraph 2 reads "Once the interpretation of a
+  numeric intrinsic operation is established, the processor may
+  evaluate any mathematically equivalent expression, provided that
+  the integrity of parentheses is not violated."
+  This compiler honors that long-standing guarantee of the language,
+  because subclause 10.1.8 ("Integrity of parentheses") requires that
+  "any expression in parentheses shall be treated as a data entity".
+  When the calculation of the value of that data entity yields
+  `REAL` or `COMPLEX`, its kind is known, which implies rounding.
+  So one needn't worry about default compilation modes breaking
+  the parentheses in cases like `(X*X)-(Y*Y)` when they're meant
+  to prevent inconsistent rounding from the use of FMA.
+  (Parentheses prevent fusion in only 4 out of 7 other compilers,
+  so this interpretation is not portable.)
+
 ## De Facto Standard Features
 
 * `EXTENDS_TYPE_OF()` returns `.TRUE.` if both of its arguments have the