[DOC-CVS] [doc-en] master: Update `ReturnTypeWillChange` intro for clarity (#5614)

Author: Mikhail Alferov (mmalferov)
Committer: GitHub (web-flow)
Pusher: kamil-tekiela
Date: 2026-07-24T22:26:01+01:00

Commit: https://github.com/php/doc-en/commit/52e88759354dd18104d8c067780be9f582f20136
Raw diff: https://github.com/php/doc-en/commit/52e88759354dd18104d8c067780be9f582f20136.diff

Update `ReturnTypeWillChange` intro for clarity (#5614)

Changed paths:
  M  language/predefined/attributes/returntypewillchange.xml
  M  reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml
  M  reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml


Diff:

diff --git a/language/predefined/attributes/returntypewillchange.xml b/language/predefined/attributes/returntypewillchange.xml
index 017bbb9c88b1..df9213e7832e 100644
--- a/language/predefined/attributes/returntypewillchange.xml
+++ b/language/predefined/attributes/returntypewillchange.xml
@@ -7,28 +7,44 @@
 
   <section xml:id="returntypewillchange.intro">
    &reftitle.intro;
+   <simpara>
+    As of PHP 8.1.0, a tentative phase of transitioning to return type declarations
+    for internal class methods began.
+   </simpara>
+
    <simpara>
     Most non-final internal methods now require overriding methods to declare
-    a compatible return type, otherwise a deprecated notice is emitted during
-    inheritance validation. This introduces a tentative return type phase:
-    the engine emits a deprecation notice instead of a fatal error when return
-    types are incompatible, before they become enforced in a future version.
+    a compatible return type. Otherwise, a deprecation notice is emitted during
+    inheritance validation warning that the signature violates covariance rules.
+   </simpara>
+
+   <simpara>
+    In a future PHP version, method signature checking will become strict,
+    and mismatches will cause a fatal error.
+   </simpara>
+
+   <simpara>
     In case the return type cannot be declared for an overriding method due to
-    PHP cross-version compatibility concerns,
-    a <code>#[\ReturnTypeWillChange]</code> attribute can be added to silence
-    the deprecation notice.
+    PHP cross-version compatibility concerns, or the overriding method declares
+    an incompatible return type, a <code>#[\ReturnTypeWillChange]</code> attribute
+    can be added to silence the deprecation notice.
    </simpara>
 
    <warning>
     <simpara>
-     The <classname>ReturnTypeWillChange</classname> attribute suppresses
-     deprecation warnings during the tentative return type phase <emphasis>only</emphasis>.
-     It has no effect when overriding methods defined in user-defined classes.
-     Once internal methods adopt strict types, mismatches in overriding method
-     signatures will cause a fatal error and this attribute will no longer have any effect.
+     When overriding methods defined in user-defined classes, return types are checked
+     strictly. A fatal error is emitted on mismatch, even if the overriding method
+     is marked with the attribute.
     </simpara>
-   </warning>
 
+    <simpara>
+     The <classname>ReturnTypeWillChange</classname> attribute suppresses deprecation
+     warnings <emphasis>only</emphasis> during the tentative return type phase.
+     After strict type checking is enforced, the attribute will stop working
+     and a mismatch in the overriding method signature of an internal class
+     will cause a fatal error.
+    </simpara>
+   </warning>
   </section>
 
   <section xml:id="returntypewillchange.synopsis">
diff --git a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml
index 850b2ed6477d..68b7a9f58d34 100644
--- a/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml
+++ b/reference/reflection/reflectionfunctionabstract/gettentativereturntype.xml
@@ -11,9 +11,9 @@
    <modifier>public</modifier> <type class="union"><type>ReflectionType</type><type>null</type></type><methodname>ReflectionFunctionAbstract::getTentativeReturnType</methodname>
    <void/>
   </methodsynopsis>
-  <para>
-   Returns the tentative return type associated with the function.
-  </para>
+  <simpara>
+   Returns the <link linkend="class.returntypewillchange">tentative return type</link> associated with the function.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
diff --git a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml
index 01cbc5e6fe57..676403af9ce4 100644
--- a/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml
+++ b/reference/reflection/reflectionfunctionabstract/hastentativereturntype.xml
@@ -11,9 +11,9 @@
    <modifier>public</modifier> <type>bool</type><methodname>ReflectionFunctionAbstract::hasTentativeReturnType</methodname>
    <void/>
   </methodsynopsis>
-  <para>
-   Returns whether the function has a tentative return type.
-  </para>
+  <simpara>
+   Returns whether the function has a <link linkend="class.returntypewillchange">tentative return type</link>.
+  </simpara>
 
  </refsect1>