From 64c183f2e215f032fab44f09b336f87c7ba83763 Mon Sep 17 00:00:00 2001
From: USAMI Kenta <tadsan@zonu.me>
Date: Tue, 14 Jul 2026 21:02:17 +0900
Subject: [PATCH] Clarify forward_static_call docs

---
 .../functions/forward-static-call-array.xml   | 33 +++++++++++--------
 .../functions/forward-static-call.xml         | 20 ++++++-----
 2 files changed, 31 insertions(+), 22 deletions(-)

diff --git a/reference/funchand/functions/forward-static-call-array.xml b/reference/funchand/functions/forward-static-call-array.xml
index d2aba7efd68e..252bf3474f9d 100644
--- a/reference/funchand/functions/forward-static-call-array.xml
+++ b/reference/funchand/functions/forward-static-call-array.xml
@@ -3,7 +3,8 @@
 <refentry xml:id="function.forward-static-call-array" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>forward_static_call_array</refname>
-  <refpurpose>Call a static method and pass the arguments as array</refpurpose>
+  <refpurpose>Call a callback while preserving the current called class, with
+   parameters as an array</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -13,15 +14,19 @@
    <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
    <methodparam><type>array</type><parameter>args</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Calls a user defined function or method given by the <parameter>callback</parameter>
    parameter. This function must be called within a method context, it can't be 
    used outside a class.
-   It uses the <link linkend="language.oop5.late-static-bindings">late static
-   binding</link>.
-   All arguments of the forwarded method are passed as values,
-   and as an array, similarly to <function>call_user_func_array</function>.
-  </para>
+   When calling a method callback, it forwards the current
+   <link linkend="language.oop5.late-static-bindings">late static binding</link>,
+   so <literal>static::</literal> inside the method resolves to the current
+   called class. This is useful for static method callbacks that should behave
+   like forwarding calls such as <literal>parent::</literal> or
+   <literal>self::</literal>.
+   Arguments for the callback are taken from the <parameter>args</parameter>
+   array, similarly to <function>call_user_func_array</function>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -41,14 +46,14 @@
     <varlistentry>
      <term><parameter>args</parameter></term>
      <listitem>
-      <para>
-       One parameter, gathering all the method parameter in one array.
-      </para>
+      <simpara>
+       The parameters to be passed to the callback, as an array.
+      </simpara>
       <note>
-       <para>
-        Note that the parameters for <function>forward_static_call_array</function> are
-        not passed by reference.
-       </para>
+       <simpara>
+        To pass a parameter by reference, the corresponding element in
+        <parameter>args</parameter> must be a reference.
+       </simpara>
       </note>
      </listitem>
     </varlistentry>
diff --git a/reference/funchand/functions/forward-static-call.xml b/reference/funchand/functions/forward-static-call.xml
index 4a89c8568124..5f399bb3acc8 100644
--- a/reference/funchand/functions/forward-static-call.xml
+++ b/reference/funchand/functions/forward-static-call.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.forward-static-call" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>forward_static_call</refname>
-  <refpurpose>Call a static method</refpurpose>
+  <refpurpose>Call a callback while preserving the current called class</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -13,13 +13,17 @@
    <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
    <methodparam rep="repeat"><type>mixed</type><parameter>args</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Calls a user defined function or method given by the <parameter>callback</parameter>
    parameter, with the following arguments. This function must be called within a method
    context, it can't be used outside a class.
-   It uses the <link linkend="language.oop5.late-static-bindings">late static
-   binding</link>.
-  </para>
+   When calling a method callback, it forwards the current
+   <link linkend="language.oop5.late-static-bindings">late static binding</link>,
+   so <literal>static::</literal> inside the method resolves to the current
+   called class. This is useful for static method callbacks that should behave
+   like forwarding calls such as <literal>parent::</literal> or
+   <literal>self::</literal>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -39,9 +43,9 @@
     <varlistentry>
      <term><parameter>args</parameter></term>
      <listitem>
-      <para>
-       Zero or more parameters to be passed to the function.
-      </para>
+      <simpara>
+       Zero or more parameters to be passed to the callback.
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>