Clarify forward_static_call docs

Author: zonuexe

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">
@@ -17,10 +18,14 @@
    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>.
+   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>.
   </para>
  </refsect1>
 
@@ -42,12 +47,12 @@
      <term><parameter>args</parameter></term>
      <listitem>
       <para>
-       One parameter, gathering all the method parameter in one array.
+       The parameters to be passed to the callback, as an array.
       </para>
       <note>
        <para>
-        Note that the parameters for <function>forward_static_call_array</function> are
-        not passed by reference.
+        To pass a parameter by reference, the corresponding element in
+        <parameter>args</parameter> must be a reference.
        </para>
       </note>
      </listitem>

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">
@@ -17,8 +17,12 @@
    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>.
+   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>.
   </para>
  </refsect1>
 
@@ -40,7 +44,7 @@
      <term><parameter>args</parameter></term>
      <listitem>
       <para>
-       Zero or more parameters to be passed to the function.
+       Zero or more parameters to be passed to the callback.
       </para>
      </listitem>
     </varlistentry>