From 6aceff3a113f80e79fbfa18689bdc9ab369aefea Mon Sep 17 00:00:00 2001
From: Hartmut Holzgraefe <hholzgra@php.net>
Date: Sat, 26 Oct 2002 06:58:16 +0000
Subject: [PATCH] - documentation on pseudo-types - "callback" pseudo-type
 added - changed usort proto to use callback (more will follow)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@101396 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/types.xml                  | 130 +++++++++++++++++++++++-----
 reference/array/functions/usort.xml |  14 +--
 2 files changed, 114 insertions(+), 30 deletions(-)

diff --git a/language/types.xml b/language/types.xml
index b1125daa19..b5952f407b 100644
--- a/language/types.xml
+++ b/language/types.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.88 $ -->
+<!-- $Revision: 1.89 $ -->
  <chapter id="language.types">
   <title>Types</title>
 
@@ -77,27 +77,35 @@
     </listitem>
 
    </itemizedlist>
+
+   This manual also introduces some 
+   <link linkend="language.pseudo-types">pseudo-types</link> 
+   for readability reasons:
+
+   <itemizedlist>
+ 
+    <listitem>
+     <simpara>
+      <link linkend="language.types.mixed">mixed</link>
+     </simpara>
+    </listitem>
+ 
+    <listitem>
+     <simpara>
+      <link linkend="language.types.number">number</link>
+     </simpara>
+    </listitem>
+ 
+    <listitem>
+     <simpara>
+      <link linkend="language.types.mixed">callback</link>
+     </simpara>
+    </listitem>
+
+   </itemizedlist>
+
   </para>
   
-  <note>
-   <simpara>
-    In this manual you'll often find <literal>mixed</literal> parameters. 
-    This pseudo-type
-    indicates multiple possibilities for that parameter.
-   </simpara>
-   <!--
-   
-   Just an idea, maybe useful for some func-defs?
-   (at least it is for the operator-defs)
-   
-   <simpara>
-    In parameter definitions you can also encounter the 'number' pseudo-type,
-    that indicates a parameter that is either <type>integer</type> or 
-    <type>float</type>.
-   </simpara>
-   -->
-  </note>
-
 
   <simpara>
    The type of a variable is usually not set by the programmer;
@@ -1827,7 +1835,89 @@ $var = NULL;
      See also <function>is_null</function> and <function>unset</function>.
     </para>
    </sect2>
+  </sect1>
+ 
+  <sect1 id="language.pseudo-types">
+   <title>Pseudo-types used in this documentation</title> 
+
+   <sect2 id="language.types.mixed">
+    <title>mixed</title>
+    <para>
+     <literal>mixed</literal> indicates that a parameter may accept multiple (but not
+     necesseraly all) types.
+    </para>
+    <para>
+     <function>gettype</function> for example will accept all PHP types,
+     while <function>str_replace</function> will accept strings and arrays.
+    </para>
+   </sect2>
   
+   <sect2 id="language.types.number">
+    <title>number</title>
+    <para>
+     <literal>number</literal> indicates that a parameter can be either
+     <type>integer</type> or <type>float</type>.
+    </para>
+   </sect2>
+
+   <sect2 id="language.types.callback">
+    <title>callback</title>
+    <para>
+     Some functions like <function>call_user_function</function> 
+     or <function>usort</function> accept user defined 
+     callback functions as a parameter. Callback functions can not only
+     be simple functions but also object methods including static class
+     methods. 
+    </para>
+    <para>
+     A PHP function is simply passed by its name as a string.
+    </para>
+    <para>
+     A method of an instantiated object is passed as an array containing
+     an object as the element with index 0 and a method name as the 
+     element with index 1.
+    </para>
+    <para>
+     Static class methods can also be passed without instantiating an
+     object of that class by passing the class name instead of an 
+     object as the element with index 0.
+    </para>
+
+    <para>
+     <example>
+      <title>
+       Callback function examples
+      </title>
+      <programlisting role="php">
+<![CDATA[
+<?php 
+
+// simple callback example
+function foobar() {
+    echo "hello world!";
+}
+call_user_function("foobar"); 
+
+// method callback examples
+class foo {
+  function bar() {
+    echo "hello world!";
+  }
+}
+
+$foo = new foo;
+
+call_user_function(array($foo, "bar")); // object method call
+
+call_user_function(array("foo", "bar")); // static class method call
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>  
+   
+   </sect2>
   </sect1>
 
   <sect1 id="language.types.type-juggling">
diff --git a/reference/array/functions/usort.xml b/reference/array/functions/usort.xml
index f1c2db7024..16c2ee7c73 100644
--- a/reference/array/functions/usort.xml
+++ b/reference/array/functions/usort.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <!-- splitted from ./en/functions/array.xml, last change in rev 1.2 -->
   <refentry id="function.usort">
    <refnamediv>
@@ -13,7 +13,7 @@
      <methodsynopsis>
       <type>void</type><methodname>usort</methodname>
       <methodparam><type>array</type><parameter>array</parameter></methodparam>
-      <methodparam><type>string</type><parameter>cmp_function</parameter></methodparam>
+      <methodparam><type>callback</type><parameter>cmp_function</parameter></methodparam>
      </methodsynopsis>
     <para>
      This function will sort an array by its values using a
@@ -116,7 +116,7 @@ $fruits[2]: lemons
 ]]>
      </screen>
     </para>
-    &note.func-callback;
+
     <para>
      <example>
       <title>
@@ -165,13 +165,7 @@ c
 d
      </screen>
     </para>
-    <warning>
-     <para>
-      The underlying quicksort function in some C libraries (such as
-      on Solaris systems) may cause PHP to crash if the comparison
-      function does not return consistent values.
-     </para>
-    </warning>
+
     <para>
      See also <function>uasort</function>,
      <function>uksort</function>, <function>sort</function>,