[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 created https://github.com/llvm/llvm-project/pull/175071

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.

>From 177af7bbb76c018793f694981ed4a7684038c518 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 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/flang/docs/Extensions.md b/flang/docs/Extensions.md
index c3837ce7ce65a..6de04601e7944 100644
--- a/flang/docs/Extensions.md
+++ b/flang/docs/Extensions.md
@@ -980,6 +980,25 @@ 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 with 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."
+  We honor that long-standing guarantee of the language, because
+  F'2023 10.1.8 "Integrity of parentheses" requires that
+  "any expression in parentheses shall be treated as a data entity",
+  and since the calculation of that data entity as a value of
+  a specific kind of `REAL` or `COMPLEX` involves rounding, it's rounded.
+  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.
+
 ## De Facto Standard Features
 
 * `EXTENDS_TYPE_OF()` returns `.TRUE.` if both of its arguments have the