- Update docu

diff --git a/ext/spl/internal/iteratoriterator.inc b/ext/spl/internal/iteratoriterator.inc
index 311008b6d568df0fc383adf5d4f71771d37294c6..147f93fadefb9771bf80ac04d35298eb40a5df6f 100755 (executable)
--- 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)
                {