Fix #75546: Clarification for how iterator_apply's $args are passed to the $function

This also integrates user note 121897.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@344631 c90b9560-bf6c-de11-be94-00142212c4b1

reference/spl/functions/iterator-apply.xml

@@ -13,7 +13,7 @@
    <type>int</type><methodname>iterator_apply</methodname>
    <methodparam><type>Traversable</type><parameter>iterator</parameter></methodparam>
    <methodparam><type>callable</type><parameter>function</parameter></methodparam>
-   <methodparam choice="opt"><type>array</type><parameter>args</parameter></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>args</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Calls a function for every element in an iterator.
@@ -28,7 +28,7 @@
      <term><parameter>iterator</parameter></term>
      <listitem>
       <para>
-       The class to iterate over.
+       The iterator object to iterate over.
       </para>
      </listitem>
     </varlistentry>
@@ -37,6 +37,9 @@
      <listitem>
       <para>
        The callback function to call on every element.
+       This function only receives the given <parameter>args</parameter>, so it
+       is nullary by default. If <literal>count($args) === 3</literal>, for
+       instance, the callback function is ternary.
        <note>
         <simpara>
          The function must return &true; in order to
@@ -50,7 +53,9 @@
      <term><parameter>args</parameter></term>
      <listitem>
       <para>
-       Arguments to pass to the callback function.
+       An <type>array</type> of arguments; each element of
+       <parameter>args</parameter> is passed to the callback
+       <parameter>function</parameter> as separate argument.
       </para>
      </listitem>
     </varlistentry>