returntypewillchange.xml Update ReturnTypeWillChange intro for clarity

language/predefined/attributes/returntypewillchange.xml

@@ -7,28 +7,45 @@
 
   <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>
+    Return type compatibility checks for internal class extensions remain in a soft mode
+    until a future PHP version enforces strict checking.
+    At that point, mismatches will cause a fatal error instead of a deprecation notice.
+   </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 an overriding method signature of an internal class
+     will cause a fatal error.
+    </simpara>
+   </warning>
   </section>
 
   <section xml:id="returntypewillchange.synopsis">

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">

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>