ReturnTypeWillChange: Add warning about future strict return type (#5613)

Author: mmalferov

language/predefined/attributes/returntypewillchange.xml

@@ -7,15 +7,28 @@
 
   <section xml:id="returntypewillchange.intro">
    &reftitle.intro;
-   <para>
+   <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.
+    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.
     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.
-   </para>
+   </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.
+    </simpara>
+   </warning>
+
   </section>
 
   <section xml:id="returntypewillchange.synopsis">