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

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>