From a1e4712d6a0223aa08d78e45e808345b9e9aa524 Mon Sep 17 00:00:00 2001
From: Peter Cowburn <salathe@php.net>
Date: Wed, 13 Jul 2011 09:39:04 +0000
Subject: [PATCH] replay reverted r313182 with fixed examples sections

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@313199 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/spl/callbackfilteriterator.xml      | 60 ++++++++++++++++
 .../spl/recursivecallbackfilteriterator.xml   | 68 +++++++++++++++++++
 .../construct.xml                             | 33 ++++++---
 .../getchildren.xml                           | 21 ++++--
 .../haschildren.xml                           | 48 +++++++++++--
 reference/spl/versions.xml                    | 10 +++
 6 files changed, 222 insertions(+), 18 deletions(-)

diff --git a/reference/spl/callbackfilteriterator.xml b/reference/spl/callbackfilteriterator.xml
index c2e714f51a..0432aad00e 100644
--- a/reference/spl/callbackfilteriterator.xml
+++ b/reference/spl/callbackfilteriterator.xml
@@ -60,6 +60,66 @@
 
   </section>
 
+  <!-- {{{ examples -->
+  <section xml:id="callbackfilteriterator.examples">
+   &reftitle.examples;
+   <para>
+    The callback should accept up to three arguments:
+    the current item, the current key and the iterator, respectively.
+   </para>
+   <example xml:id="callbackfilteriterator.examples.args">
+    <title>Available callback arguments</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+/**
+ * Callback for CallbackFilterIterator
+ *
+ * @param $current   Current item's value
+ * @param $key       Current item's key
+ * @param $iterator  Iterator being filtered
+ * @return boolean   TRUE to accept the current item, FALSE otherwise
+ */
+function my_callback($current, $key, $iterator) {
+    // Your filtering code here
+}
+
+?>
+]]>
+    </programlisting>
+   </example>
+   <para>
+    Any <type>callback</type> may be used; such as a string containing a
+    function name, an array for a method, or an anonymous function.
+   </para>
+   <example xml:id="callbackfilteriterator.examples.basic">
+    <title>Callback basic examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$dir = new FilesystemIterator(__DIR__);
+
+// Filter large files ( > 100MB)
+function is_large_file($current) {
+    return $current->isFile() && $current->getSize() > 104857600;
+}
+$large_files = new CallbackFilterIterator($dir, 'is_large_file');
+
+// Filter directories
+$files = new CallbackFilterIterator($dir, function ($current, $key, $iterator) {
+    return $current->isDir() && ! $iterator->isDot();
+});
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </section>
+  <!-- }}} -->
+
+
  </partintro>
 
  &reference.spl.entities.callbackfilteriterator;
diff --git a/reference/spl/recursivecallbackfilteriterator.xml b/reference/spl/recursivecallbackfilteriterator.xml
index dc66d1251f..9fa61c7806 100644
--- a/reference/spl/recursivecallbackfilteriterator.xml
+++ b/reference/spl/recursivecallbackfilteriterator.xml
@@ -64,6 +64,74 @@
 
   </section>
 
+  <!-- {{{ examples -->
+  <section xml:id="recursivecallbackfilteriterator.examples">
+   &reftitle.examples;
+   <para>
+    The callback should accept up to three arguments:
+    the current item, the current key and the iterator, respectively.
+   </para>
+   <example xml:id="recursivecallbackfilteriterator.examples.args">
+    <title>Available callback arguments</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+/**
+ * Callback for RecursiveCallbackFilterIterator
+ *
+ * @param $current   Current item's value
+ * @param $key       Current item's key
+ * @param $iterator  Iterator being filtered
+ * @return boolean   TRUE to accept the current item, FALSE otherwise
+ */
+function my_callback($current, $key, $iterator) {
+    // Your filtering code here
+}
+
+?>
+]]>
+    </programlisting>
+   </example>
+   <para>
+    Filtering a recursive iterator generally involves two conditions.
+    The first is that, to allow recursion, the callback function should return &true;
+    if the current iterator item has children.
+    The second is the normal filter condition, such as a file size or extension 
+    check as in the example below.
+   </para>
+   <example xml:id="recursivecallbackfilteriterator.examples.basic">
+    <title>Recursive callback basic example</title>
+<programlisting role="php">
+<![CDATA[
+<?php
+
+$dir = new FilesystemIterator(__DIR__);
+
+// Filter large files ( > 100MB)
+$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
+    // Allow recursion
+    if ($iterator->hasChildren()) {
+        return TRUE;
+    }
+    // Check for large file
+    if ($current->isFile() && $current->getSize() > 104857600) {
+        return TRUE;
+    }
+    return FALSE;
+});
+ 
+foreach (new RecursiveIteratorIterator($files) as $file) {
+    echo $file->getPathname() . PHP_EOL;
+}
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </section>
+  <!-- }}} -->
+
  </partintro>
 
  &reference.spl.entities.recursivecallbackfilteriterator;
diff --git a/reference/spl/recursivecallbackfilteriterator/construct.xml b/reference/spl/recursivecallbackfilteriterator/construct.xml
index d9540eb5be..076db992a4 100644
--- a/reference/spl/recursivecallbackfilteriterator/construct.xml
+++ b/reference/spl/recursivecallbackfilteriterator/construct.xml
@@ -9,17 +9,17 @@
 
  <refsect1 role="description">
   &reftitle.description;
-  <methodsynopsis>
+  <constructorsynopsis role="oop">
+   <modifier>public</modifier>
    <methodname>RecursiveCallbackFilterIterator::__construct</methodname>
    <methodparam><type>RecursiveIterator</type><parameter>iterator</parameter></methodparam>
    <methodparam><type>string</type><parameter>callback</parameter></methodparam>
-  </methodsynopsis>
+  </constructorsynopsis>
   <para>
-
+   Creates a filtered iterator from a <interfacename>RecursiveIterator</interfacename>
+   using the <parameter>callback</parameter> to determine which 
+   items are accepted or rejected.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +29,7 @@
     <term><parameter>iterator</parameter></term>
     <listitem>
      <para>
-      
+      The recursive iterator to be filtered.
      </para>
     </listitem>
    </varlistentry>
@@ -37,7 +37,12 @@
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
-      
+      The callback, which should return &true; to accept the current item
+      or &false; otherwise.
+      See <link linkend="recursivecallbackfilteriterator.examples">Examples</link>.
+     </para>
+     <para>
+      May be any valid <type>callback</type> value.
      </para>
     </listitem>
    </varlistentry>
@@ -47,10 +52,20 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   &return.void;
   </para>
  </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><link linkend="recursivecallbackfilteriterator.examples">RecursiveCallbackFilterIterator Examples</link></member>
+    <member><methodname>RecursiveCallbackFilterIterator::getChildren</methodname></member>
+    <member><methodname>RecursiveCallbackFilteriterator::hasChildren</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 
 </refentry>
 
diff --git a/reference/spl/recursivecallbackfilteriterator/getchildren.xml b/reference/spl/recursivecallbackfilteriterator/getchildren.xml
index de40a38739..1a656e1214 100644
--- a/reference/spl/recursivecallbackfilteriterator/getchildren.xml
+++ b/reference/spl/recursivecallbackfilteriterator/getchildren.xml
@@ -14,11 +14,12 @@
    <void />
   </methodsynopsis>
   <para>
-
+   Fetches the filtered children of the inner iterator.
+  </para>
+  <para>
+   <methodname>RecursiveCallbackFilterIterator::hasChildren</methodname> should be used
+   to determine if there are children to be fetched.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +30,19 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
+   Returns a <classname>RecursiveCallbackFilterIterator</classname> containing
+   the children.
+  </para>
+ </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><link linkend="recursivecallbackfilteriterator.examples">RecursiveCallbackFilterIterator Examples</link></member>
+    <member><methodname>RecursiveCallbackFilterIterator::__construct</methodname></member>
+    <member><methodname>RecursiveCallbackFilteriterator::hasChildren</methodname></member>
+   </simplelist>
   </para>
  </refsect1>
 
diff --git a/reference/spl/recursivecallbackfilteriterator/haschildren.xml b/reference/spl/recursivecallbackfilteriterator/haschildren.xml
index 906fa3c8ea..84cae075b6 100644
--- a/reference/spl/recursivecallbackfilteriterator/haschildren.xml
+++ b/reference/spl/recursivecallbackfilteriterator/haschildren.xml
@@ -14,11 +14,8 @@
    <void />
   </methodsynopsis>
   <para>
-
+   Returns &true; if the current element has children, &false; otherwise.
   </para>
-
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,10 +26,51 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   Returns &true; if the current element has children, &false; otherwise.
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example xml:id="recursivecallbackfilteriterator.haschildren.examples.basic">
+    <title><methodname>RecursiveCallbackFilterIterator::hasChildren</methodname> basic usage</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$dir = new FilesystemIterator(__DIR__);
+
+// Recursively iterate over XML files
+$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
+    // Allow recursion into directories
+    if ($iterator->hasChildren()) {
+        return TRUE;
+    }
+    // Check for XML file
+    if (!strcasecmp($current->getExtension(), 'xml')) {
+        return TRUE;
+    }
+    return FALSE;
+});
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><link linkend="recursivecallbackfilteriterator.examples">RecursiveCallbackFilterIterator Examples</link></member>
+    <member><methodname>RecursiveCallbackFilterIterator::__construct</methodname></member>
+    <member><methodname>RecursiveCallbackFilteriterator::getChildren</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
 
 </refentry>
 
diff --git a/reference/spl/versions.xml b/reference/spl/versions.xml
index 71224d1bec..8c94c179be 100644
--- a/reference/spl/versions.xml
+++ b/reference/spl/versions.xml
@@ -1020,6 +1020,16 @@
  <function name='multipleiterator::key' from='PHP 5 &gt;= 5.3.0'/>
  <function name='multipleiterator::current' from='PHP 5 &gt;= 5.3.0'/>
  <function name='multipleiterator::next' from='PHP 5 &gt;= 5.3.0'/>
+
+ <function name='callbackfilteriterator' from='PHP 5 &gt;= 5.4.0'/>
+ <function name='callbackfilteriterator::__construct' from='PHP 5 &gt;= 5.4.0'/>
+ <function name='callbackfilteriterator::accept' from='PHP 5 &gt;= 5.4.0'/>
+
+ <function name='recursivecallbackfilteriterator' from='PHP 5 &gt;= 5.4.0'/>
+ <function name='recursivecallbackfilteriterator::__construct' from='PHP 5 &gt;= 5.4.0'/>
+ <function name='recursivecallbackfilteriterator::getchildren' from='PHP 5 &gt;= 5.4.0'/>
+ <function name='recursivecallbackfilteriterator::haschildren' from='PHP 5 &gt;= 5.4.0'/>
+
 </versions>
 
 <!-- Keep this comment at the end of the file