[llvm] [LangRef] Clarify to exclude norecurse attribute when any call paths through external functions is present (PR #157087)

[Usha Gupta via llvm-commits]

https://github.com/usha1830 updated https://github.com/llvm/llvm-project/pull/157087

>From 6df0f1de81997edbf47c2fbc5407975e600d03f5 Mon Sep 17 00:00:00 2001
From: Usha Gupta <usha.gupta at arm.com>
Date: Fri, 5 Sep 2025 11:50:55 +0000
Subject: [PATCH 1/2] [LangRef] Clarify to exclude norecurse attribute when any
 call path through external functions is present.

---
 llvm/docs/LangRef.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index e64b9343b7622..787592a85971e 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -2256,9 +2256,12 @@ For example:
     behavior at runtime if the function ever does dynamically return. Annotated
     functions may still raise an exception, i.a., ``nounwind`` is not implied.
 ``norecurse``
-    This function attribute indicates that the function does not call itself
-    either directly or indirectly down any possible call path. This produces
-    undefined behavior at runtime if the function ever does recurse.
+    This function attribute indicates that the function does not participate in
+    recursion, either directly or through mutual recursion. At runtime it is
+    undefined behavior if any dynamic call stack contains this function more
+    than once at the same time. A function must not be marked ``norecurse`` if,
+    along any call path starting from its body, control may reach an external
+    function whose definition is not available.
 
 .. _langref_willreturn:
 

>From e98472df3bd460abfddca1a618638a203ce998c7 Mon Sep 17 00:00:00 2001
From: Usha Gupta <usha.gupta at arm.com>
Date: Fri, 5 Sep 2025 15:50:36 +0000
Subject: [PATCH 2/2] Rephrase as per comments

---
 llvm/docs/LangRef.rst | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 787592a85971e..5fa80540cd76a 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -2256,12 +2256,16 @@ For example:
     behavior at runtime if the function ever does dynamically return. Annotated
     functions may still raise an exception, i.a., ``nounwind`` is not implied.
 ``norecurse``
-    This function attribute indicates that the function does not participate in
-    recursion, either directly or through mutual recursion. At runtime it is
-    undefined behavior if any dynamic call stack contains this function more
-    than once at the same time. A function must not be marked ``norecurse`` if,
-    along any call path starting from its body, control may reach an external
-    function whose definition is not available.
+    This function attribute indicates that the function is not recursive and
+    does not participate in recursion. This means that the function never
+    occurs inside a cycle in the dynamic call graph.
+    For example:
+
+.. code-block:: llvm
+
+    fn -> other_fn -> fn       ; fn is not norecurse
+    other_fn -> fn -> other_fn ; fn is not norecurse
+    fn -> other_fn -> other_fn ; fn is norecurse
 
 .. _langref_willreturn: