From d46982681a7a36c4216d41098a3f71b395d9b71d Mon Sep 17 00:00:00 2001
From: Brett Bieber <saltybeagle@php.net>
Date: Fri, 14 Nov 2008 18:41:09 +0000
Subject: [PATCH] add some examples for DirectoryIterator.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@269010 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/spl/directoryiterator.xml           |  5 ++-
 reference/spl/directoryiterator/construct.xml | 43 +++++++++++++++----
 reference/spl/directoryiterator/isdot.xml     | 33 +++++++++++---
 reference/spl/directoryiterator/islink.xml    | 41 +++++++++++++++++-
 4 files changed, 104 insertions(+), 18 deletions(-)

diff --git a/reference/spl/directoryiterator.xml b/reference/spl/directoryiterator.xml
index a82cdae566..d9e7579fb6 100644
--- a/reference/spl/directoryiterator.xml
+++ b/reference/spl/directoryiterator.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <phpdoc:classref xmlns:phpdoc="http://php.net/ns/phpdoc" xml:id="class.directoryiterator" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>The DirectoryIterator class</title>
  <titleabbrev>DirectoryIterator</titleabbrev>
@@ -10,7 +10,8 @@
   <section xml:id="directoryiterator.intro">
    &reftitle.intro;
    <para>
-    ...
+    The DirectoryIterator class provides a simple interface for viewing
+    the contents of filesystem directories.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/spl/directoryiterator/construct.xml b/reference/spl/directoryiterator/construct.xml
index 183a9517ad..60966ec4ff 100644
--- a/reference/spl/directoryiterator/construct.xml
+++ b/reference/spl/directoryiterator/construct.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="directoryiterator.construct" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>DirectoryIterator::__construct</refname>
@@ -13,10 +13,8 @@
    <methodparam><type>string</type><parameter>path</parameter></methodparam>
   </constructorsynopsis>
 
-   &warn.undocumented.func;
-
   <para>
-   Constructs a new dir iterator from a path.
+   Constructs a new directory iterator from a path.
   </para>
  </refsect1>
 
@@ -28,18 +26,45 @@
      <term><parameter>path</parameter></term>
      <listitem>
       <para>
-       The path.
+       The path of the directory to iterate.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect1>
-
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
-   &return.void;
+   <example>
+    <title>A <methodname>DirectoryIterator::__construct</methodname> example</title>
+     <para>
+      This example will list the contents of the directory containing the script.
+     </para>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$dir = new DirectoryIterator(dirname(__FILE__));
+foreach ($dir as $fileinfo) {
+    if (!$fileinfo->isDot()) {
+        echo 'Filename '.$fileinfo->getFilename().PHP_EOL;
+    }
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><link linkend="class.splfileinfo">SplFileInfo class</link></member>
+    <member><link linkend="interface.iterator">Iterator interface</link></member>
+   </simplelist>
   </para>
  </refsect1>
 
diff --git a/reference/spl/directoryiterator/isdot.xml b/reference/spl/directoryiterator/isdot.xml
index fa8bcd6c7f..13e82cdb8f 100644
--- a/reference/spl/directoryiterator/isdot.xml
+++ b/reference/spl/directoryiterator/isdot.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="directoryiterator.isdot" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>DirectoryIterator::isDot</refname>
@@ -12,11 +12,9 @@
    <void/>
   </methodsynopsis>
 
-   &warn.undocumented.func;
-
   <para>
-   Check whether it's a directory and either <literal>.</literal>
-   or <literal>..</literal>.
+   Check whether the current entry is a directory and either
+   <literal>.</literal> or <literal>..</literal>.
   </para>
  </refsect1>
 
@@ -32,6 +30,31 @@
    otherwise &false;
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>A <methodname>DirectoryIterator::isDot</methodname> example</title>
+    <para>
+      This example will list all files, omitting the <literal>.</literal> and
+      <literal>..</literal> entries.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$dir = new DirectoryIterator(dirname(__FILE__));
+foreach ($dir as $fileinfo) {
+    if (!$fileinfo->isDot()) {
+        echo 'Filename '.$fileinfo->getFilename().PHP_EOL;
+    }
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
 
 </refentry>
 
diff --git a/reference/spl/directoryiterator/islink.xml b/reference/spl/directoryiterator/islink.xml
index 8fa96595ce..011299a10e 100644
--- a/reference/spl/directoryiterator/islink.xml
+++ b/reference/spl/directoryiterator/islink.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry xml:id="directoryiterator.islink" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>DirectoryIterator::isLink</refname>
@@ -15,7 +15,7 @@
    &warn.undocumented.func;
 
   <para>
-   Checks if the entry is a symbolic link.
+   Checks if the current element is a symbolic link.
   </para>
  </refsect1>
 
@@ -30,6 +30,43 @@
    &true; if the entry is a symbolic link, otherwise &false;
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>A <methodname>DirectoryIterator::isLink</methodname> example</title>
+    <para>
+     This example contains a recursive function for removing a directory tree.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+/**
+ * This function will recursively delete all files in the given path, without
+ * following symlinks.
+ * 
+ * @param string $path Path to the directory to remove.
+ */
+function removeDir($path) {
+    $dir = new DirectoryIterator($path);
+    foreach ($dir as $fileinfo) {
+        if ($fileinfo->isFile() || $fileinfo->isSymlink()) {
+            unlink($fileinfo->getPathName());
+        } elseif (!$fileinfo->isDot() && $fileinfo->isDir()) {
+            removeDir($fileinfo->getPathName());
+        }
+    }
+    rmdir($path);
+}
+
+removeDir('foo');
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
 
 </refentry>