- Update docu

1 files changed, 27 insertions, 3 deletions

diff --git a/ext/spl/internal/iteratoriterator.inc b/ext/spl/internal/iteratoriterator.inc
index 311008b6d5..147f93fade 100755
--- a/ext/spl/internal/iteratoriterator.inc
+++ b/ext/spl/internal/iteratoriterator.inc
@@ -12,15 +12,39 @@
 /** @ingroup SPL
  * @brief Basic Iterator wrapper
  * @since PHP 5.1
+ *
+ * This iterator wrapper allows to convert anything that is traversable into 
+ * an Iterator. It is very important to understand that most classes that do 
+ * not implement Iterator have their reasone to. Most likely they do not allow
+ * the full Iterator feature set. If so you need to provide techniques to
+ * prevent missuse. If you do not you must expect exceptions or fatal erros.
+ *
+ * It is also possible to derive the class and implement IteratorAggregate by
+ * downcasting the instances returned in getIterator. See the following
+ * example (assuming BaseClass implements Traversable):
+ \code
+ class SomeClass extends BaseClass implements IteratorAggregate
+ {
+   function getIterator()
+   {
+     return new IteratorIterator($this, 'BaseClass');
+   }
+ }
+ \endcode
+ *
+ * As you can see in the example this approach requires that the class to 
+ * downcast to is actually a base class of the specified iterator to wrap.
+ * Omitting the downcast in the above example would result in an endless loop
+ * since IteratorIterator::__construct() would call SomeClass::getIterator().
  */
 class IteratorIterator implements OuterIterator
 {
 	/** Construct an IteratorIterator from an Iterator or an IteratorAggregate.
 	 *
-	 * Classes that only implement Traversable can be wrapped only after 
-	 * converting class IteratorIterator into c code.
+	 * @param iterator  inner iterator
+	 * @param classname optional class the iterator has to be downcasted to
 	 */
-	function __construct(Traversable $iterator)
+	function __construct(Traversable $iterator, $classname = null)
 	{
 		if ($iterator instanceof IteratorAggregate)
 		{