From d41f9c2347e53ade9538a0adc0dca7e75008020b Mon Sep 17 00:00:00 2001
From: Peter Cowburn <salathe@php.net>
Date: Wed, 23 Sep 2009 18:59:41 +0000
Subject: [PATCH] Filling out InfiniteIterator documentation

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@288618 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/spl/infiniteiterator.xml           |  5 +-
 reference/spl/infiniteiterator/construct.xml | 54 +++++++++++++++++---
 reference/spl/infiniteiterator/next.xml      | 16 +++---
 3 files changed, 61 insertions(+), 14 deletions(-)

diff --git a/reference/spl/infiniteiterator.xml b/reference/spl/infiniteiterator.xml
index 5375b29e00..2706f0868f 100644
--- a/reference/spl/infiniteiterator.xml
+++ b/reference/spl/infiniteiterator.xml
@@ -12,8 +12,9 @@
   <section xml:id="infiniteiterator.intro">
    &reftitle.intro;
    <para>
-    This Iterator takes another Iterator and infinitely iterates it
-    by rewinding it when its end is reached.
+    The <classname>InfiniteIterator</classname> allows one to
+    infinitely iterate over an iterator without having to manually
+    rewind the iterator upon reaching its end.
    </para>
   </section>
 <!-- }}} -->
diff --git a/reference/spl/infiniteiterator/construct.xml b/reference/spl/infiniteiterator/construct.xml
index 056dc5dc7d..c8dc33c09a 100644
--- a/reference/spl/infiniteiterator/construct.xml
+++ b/reference/spl/infiniteiterator/construct.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="infiniteiterator.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>InfiniteIterator::__construct</refname>
-  <refpurpose>Constructs an infiniteIterator</refpurpose>
+  <refpurpose>Constructs an InfiniteIterator</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,10 @@
    <methodparam><type>Iterator</type><parameter>iterator</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Constructs an infinite iterator.
+   Constructs an <classname>InfiniteIterator</classname>
+   from an <classname>Iterator</classname>.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -29,7 +28,7 @@
      <term><parameter>iterator</parameter></term>
      <listitem>
       <para>
-       The passed in iterator.
+       The iterator to infinitely iterate over.
       </para>
      </listitem>
     </varlistentry>
@@ -40,7 +39,50 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   An infinite iterator.
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Throws an <constant>E_RECOVERABLE_ERROR</constant> if the
+   <parameter>iterator</parameter> parameter is not
+   an <classname>Iterator</classname>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>InfiniteIterator::__construct</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$arrayit  = new ArrayIterator(array('cat','dog'));
+$infinite = new InfiniteIterator($arrayit);
+$limit    = new LimitIterator($infinite, 0, 7);
+foreach($limit as $value)
+{
+    echo "$value\n";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+cat
+dog
+cat
+dog
+cat
+dog
+cat
+]]>
+    </screen>
+   </example>
   </para>
  </refsect1>
 
diff --git a/reference/spl/infiniteiterator/next.xml b/reference/spl/infiniteiterator/next.xml
index 90d41137e9..47215ceb5d 100644
--- a/reference/spl/infiniteiterator/next.xml
+++ b/reference/spl/infiniteiterator/next.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="infiniteiterator.next" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>InfiniteIterator::next</refname>
-  <refpurpose>Moves the Iterator forward</refpurpose>
+  <refpurpose>Moves the inner Iterator forward or rewinds it</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,15 @@
    <void />
   </methodsynopsis>
   <para>
-   Moves the inner Iterator forward to its next element, or rewind it.
+   Moves the inner <classname>Iterator</classname> forward to its next element if there is one,
+   otherwise rewinds the inner <classname>Iterator</classname> back to the beginning.
   </para>
-
-  &warn.undocumented.func;
-
+  <note>
+   <para>
+    Even an <classname>InfiniteIterator</classname> stops if 
+    its inner <classname>Iterator</classname> is empty.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -37,7 +41,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><methodname>Infinite::Iterator</methodname></member>
+    <member><methodname>InfiniteIterator::__construct</methodname></member>
    </simplelist>
   </para>
  </refsect1>