[llvm] [LangRef] make consequences of NaN rules for pow(i) more explicit (PR #170177)

[Ralf Jung via llvm-commits]

https://github.com/RalfJung created https://github.com/llvm/llvm-project/pull/170177

The NaN section says

> Floating-point math operations are allowed to treat all NaNs as if they were quiet NaNs. For example, “pow(1.0, SNaN)” may be simplified to 1.0.

This seems worth also spelling out in the section for `pow` (and `powi` which has a similar situation), to have everything concerning those operations in a single place.

>From 6a70498f489270ff8b35a7881e5da2321f7a0550 Mon Sep 17 00:00:00 2001
From: Ralf Jung <post at ralfj.de>
Date: Mon, 1 Dec 2025 18:54:47 +0100
Subject: [PATCH] [LangRef] make consequences of NaN rules for pow(i) more
 explicit

---
 llvm/docs/LangRef.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 02865f8a29c67..292f70f062bd2 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -16269,6 +16269,11 @@ Semantics:
 This function returns the first value raised to the second power with an
 unspecified sequence of rounding operations.
 
+Note that due to how :ref:`LLVM treats NaN values <floatnan>`, the special case
+of `powi(SNaN, 0.0)` can non-deterministically return *either* some NaN value
+(using the usual NaN propagation rules, so in particular the result could be
+either a signaling NaN or a quiet NaN), *or* the value `1.0`.
+
 .. _t_llvm_sin:
 
 '``llvm.sin.*``' Intrinsic
@@ -16831,6 +16836,12 @@ trapping or setting ``errno``.
 When specified with the fast-math-flag 'afn', the result may be approximated
 using a less accurate calculation.
 
+Note that due to how :ref:`LLVM treats NaN values <floatnan>`, the special cases
+of `pow(1.0, SNaN)` and `pow(SNaN, 0.0)` can non-deterministically return
+*either* some NaN value (using the usual NaN propagation rules, so in particular
+the result could be either a signaling NaN or a quiet NaN), *or* the value
+`1.0`.
+
 .. _int_exp:
 
 '``llvm.exp.*``' Intrinsic