Redesign is_callable() page (#4145)

Author: kamil-tekiela

reference/var/functions/is-callable.xml

@@ -17,7 +17,9 @@
    <methodparam choice="opt"><type>string</type><parameter role="reference">callable_name</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Verify that a value is a <type>callable</type>.
+   Verifies that <parameter>value</parameter> is a <type>callable</type>,
+   or that it can be called using the
+   <function>call_user_func</function> function.
   </para>
  </refsect1>
 
@@ -29,7 +31,7 @@
      <term><parameter>value</parameter></term>
      <listitem>
       <para>
-       The value to check
+       The value to be checked.
       </para>
      </listitem>
     </varlistentry>
@@ -38,10 +40,10 @@
      <listitem>
       <para>
        If set to &true; the function only verifies that
-       <parameter>value</parameter> might be a function or method. It will only
-       reject simple variables that are not strings, or an array that does
-       not have a valid structure to be used as a callback. The valid ones
-       are supposed to have only 2 entries, the first of which is an object
+       <parameter>value</parameter> might be a function or method. It will
+       reject any values that are neither callable objects, strings nor arrays
+       with a valid structure to be used as a callback. A valid callable array
+       has 2 entries, the first of which is an object
        or a string, and the second a string.
       </para>
      </listitem>
@@ -50,10 +52,10 @@
      <term><parameter>callable_name</parameter></term>
      <listitem>
       <para>
-       Receives the "callable name".  In the example below it is
-       "someClass::someMethod".  Note, however, that despite the implication
-       that someClass::SomeMethod() is a callable static method, this is not
-       the case.
+       Receives the "callable name", e.g.
+       <literal>"SomeClass::someMethod"</literal>. Note, however, that despite
+       the implication that <literal>SomeClass::someMethod()</literal> is a
+       callable static method, this is not the case.
       </para>
      </listitem>
     </varlistentry>
@@ -73,46 +75,60 @@
   &reftitle.examples;
   <para>
    <example>
-    <title><function>is_callable</function> example</title>
+    <title>Checking whether a string can be called as a function</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-// How to check a variable to see if it can be called
-// as a function.
-
-//
-// Simple variable containing a function
-//
 
 function someFunction() {}
 
 $functionVariable = 'someFunction';
 
-var_dump(is_callable($functionVariable, false, $callable_name)); // bool(true)
+var_dump(is_callable($functionVariable, false, $callable_name));
 
-echo $callable_name, "\n"; // someFunction
+var_dump($callable_name);
 
-//
-// Array containing a method
-//
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+bool(true)
+string(12) "someFunction"
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Checking whether an array can be called as a function</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 
-class someClass
+class SomeClass
 {
     public function someMethod() {}
 }
 
-$anObject = new someClass();
+$anObject = new SomeClass();
 
 $methodVariable = [$anObject, 'someMethod'];
 
-var_dump(is_callable($methodVariable, true, $callable_name)); // bool(true)
+var_dump(is_callable($methodVariable, true, $callable_name));
 
-echo $callable_name, "\n"; // someClass::someMethod
+var_dump($callable_name);
 
 ?>
 ]]>
     </programlisting>
-   </example>   
+    &example.outputs;
+    <screen>
+<![CDATA[
+bool(true)
+string(21) "SomeClass::someMethod"
+]]>
+    </screen>
+   </example>
    <example>
     <title><function>is_callable</function> and constructors</title>
     <simpara>
@@ -173,6 +189,7 @@ bool(false)
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>call_user_func</function></member>
     <member><function>function_exists</function></member>
     <member><function>method_exists</function></member>
    </simplelist>