From b67ca452c33a595f6f1382e32c441943a343353e Mon Sep 17 00:00:00 2001
From: Marcus Boerger <helly@php.net>
Date: Fri, 29 Oct 2004 20:58:58 +0000
Subject: [PATCH] - Update docu

---
 ext/spl/internal/cachingiterator.inc          | 42 ++++++++++++++++++
 ext/spl/internal/cachingrecursiveiterator.inc | 36 +++++++++++++++-
 ext/spl/internal/filteriterator.inc           | 11 ++++-
 ext/spl/internal/limititerator.inc            | 40 ++++++++++++++++-
 ext/spl/internal/outeriterator.inc            | 17 ++++++--
 ext/spl/internal/parentiterator.inc           | 27 ++++++++++++
 ext/spl/internal/recursiveiterator.inc        | 19 ++++++++
 .../internal/recursiveiteratoriterator.inc    | 43 +++++++++++++++++--
 ext/spl/internal/seekableiterator.inc         | 13 +++++-
 9 files changed, 237 insertions(+), 11 deletions(-)

diff --git a/ext/spl/internal/cachingiterator.inc b/ext/spl/internal/cachingiterator.inc
index a474131b5c..f1b896d05d 100755
--- a/ext/spl/internal/cachingiterator.inc
+++ b/ext/spl/internal/cachingiterator.inc
@@ -1,8 +1,23 @@
 <?php
 
+/** @file cachingiterator.inc
+ * @ingroup Internal
+ * @brief class CachingIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
 define('CIT_CALL_TOSTRING', 1);
 define('CIT_CATCH_GET_CHILD', 2);
 
+/**
+ * @brief   Cached Iteration over another Iterator
+ * @author  Marcus Boerger
+ * @version 1.1
+ *
+ */
 class CachingIterator implements OuterIterator
 {
 	protected $it;
@@ -11,6 +26,12 @@ class CachingIterator implements OuterIterator
 	protected $valid;
 	protected $strValue;
 
+	/** Construct from another iterator
+	 *
+	 * @param it    Iterator to cache
+	 * @param flags Bitmask: 
+	 *              - CIT_CALL_TOSTRING  (whether to call __toString() for every element)
+	 */
 	function __construct(Iterator $it, $flags = CIT_CALL_TOSTRING)
 	{
 		$this->it = $it;
@@ -18,12 +39,16 @@ class CachingIterator implements OuterIterator
 		$this->next();
 	}
 
+	/** Rewind the Iterator
+	 */
 	function rewind()
 	{
 		$this->it->rewind();
 		$this->next();
 	}
 	
+	/** Forward to the next element
+	 */
 	function next()
 	{
 		if ($this->valid = $this->it->valid()) {
@@ -44,31 +69,45 @@ class CachingIterator implements OuterIterator
 		$this->it->next();
 	}
 	
+	/** @return whether teh iterator is valid
+	 */
 	function valid()
 	{
 		return $this->valid;
 	}
 
+	/** @return whether there is one more element
+	 */
 	function hasNext()
 	{
 		return $this->it->valid();
 	}
 	
+	/** @return the current element
+	 */
 	function current()
 	{
 		return $this->current;
 	}
 
+	/** @return the current key
+	 */
 	function key()
 	{
 		return $this->key;
 	}
 
+	/** Aggregate the inner iterator
+	 */
 	function __call($func, $params)
 	{
 		return call_user_func_array(array($this->it, $func), $params);
 	}
 	
+	/** @return the string represenatation that was generated for the current 
+	 *          element
+	 * @throw exception when CIT_CALL_TOSTRING was not specified in constructor
+	 */
 	function __toString()
 	{
 		if (!$this->flags & CIT_CALL_TOSTRING) {
@@ -77,6 +116,9 @@ class CachingIterator implements OuterIterator
 		return $this->strValue;
 	}
 	
+	/**
+	 * @return The inner iterator
+	 */	
 	function getInnerIterator()
 	{
 		return $this->it;
diff --git a/ext/spl/internal/cachingrecursiveiterator.inc b/ext/spl/internal/cachingrecursiveiterator.inc
index fc7d9a7220..d731c7a725 100755
--- a/ext/spl/internal/cachingrecursiveiterator.inc
+++ b/ext/spl/internal/cachingrecursiveiterator.inc
@@ -1,15 +1,38 @@
 <?php
 
+/** @file cachingrecursiveiterator.inc
+ * @ingroup Internal
+ * @brief class CachingRecursiveIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
+/**
+ * @brief   
+ * @author  Marcus Boerger
+ * @version 1.1
+ */
 class CachingRecursiveIterator extends CachingIterator implements RecursiveIterator
 {
 	protected $hasChildren;
 	protected $getChildren;
 
+	/** Construct from another iterator
+	 *
+	 * @param it    Iterator to cache
+	 * @param flags Bitmask: 
+	 *              - CIT_CALL_TOSTRING   (whether to call __toString() for every element)
+	 *              - CIT_CATCH_GET_CHILD (whether to catch exceptions when trying to get childs)
+	 */
 	function __construct(RecursiveIterator $it, $flags = CIT_CALL_TOSTRING)
 	{
 		parent::__construct($it, $flags);
 	}
-	
+
+	/** Rewind Iterator
+	 */	
 	function rewind();
 	{
 	   $this->hasChildren = false;
@@ -17,6 +40,9 @@ class CachingRecursiveIterator extends CachingIterator implements RecursiveItera
 	   parent::rewind();
 	}
 
+	/** Forward to next element if necessary then an Iterator for the Children
+	 * will be created.
+	 */
 	function next()
 	{
 		if ($this->hasChildren = $this->it->hasChildren()) {
@@ -39,11 +65,19 @@ class CachingRecursiveIterator extends CachingIterator implements RecursiveItera
 		parent::next();
 	}
 
+	/** @return whether the current element has children
+	 * @note The check whether the Iterator for the children can be created was
+	 *       already executed. Hence when flag CIT_CATCH_GET_CHILD was given in
+	 *       constructor this fucntion returns false so that getChildren does 
+	 *       not try to access those children.
+	 */
 	function hasChildren()
 	{
 		return $this->hasChildren;
 	}
 
+	/** @return An Iterator for the children
+	 */
 	function getChildren()
 	{
 		return $this->getChildren;
diff --git a/ext/spl/internal/filteriterator.inc b/ext/spl/internal/filteriterator.inc
index 73c993af84..c5f27bd47d 100755
--- a/ext/spl/internal/filteriterator.inc
+++ b/ext/spl/internal/filteriterator.inc
@@ -1,9 +1,18 @@
 <?php
 
+/** @file filteriterator.inc
+ * @ingroup Internal
+ * @brief class FilterIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
 /**
  * @brief   Regular expression filter for string iterators
  * @author  Marcus Boerger
- * @version 1.0
+ * @version 1.1
  *
  * Instances of this class act as a filter around iterators. In other words 
  * you can put an iterator into the constructor and the instance will only 
diff --git a/ext/spl/internal/limititerator.inc b/ext/spl/internal/limititerator.inc
index 4625ae9f22..0a27707079 100755
--- a/ext/spl/internal/limititerator.inc
+++ b/ext/spl/internal/limititerator.inc
@@ -1,5 +1,20 @@
 <?php
 
+/** @file limititerator.inc
+ * @ingroup Internal
+ * @brief class LimitIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
+/**
+ * @brief   Limited Iteration over another Iterator
+ * @author  Marcus Boerger
+ * @version 1.1
+ *
+ */
 class LimitIterator implements OuterIterator
 {
 	protected $it;
@@ -7,7 +22,12 @@ class LimitIterator implements OuterIterator
 	protected $count;
 	private $pos;
 
-	// count === NULL means all
+	/** Construct
+	 *
+	 * @param it     Iterator to limit
+	 * @param offset Offset to first element
+	 * @param count  Maximum number of elements to show or NULL for all
+	 */
 	function __construct(Iterator $it, $offset = 0, $count = -1)
 	{
 		if ($offset < 0) {
@@ -22,6 +42,11 @@ class LimitIterator implements OuterIterator
 		$this->pos    = 0;
 	}
 	
+	/** Seek to specified position
+	 * @param position offset to seek to (relative to beginning not offset
+	 *                 specified in constructor).
+	 * @throw exception when position is invalid
+	 */
 	function seek($position) {
 		if ($position < $this->offset) {
 			throw new exception('Cannot seek to '.$position.' which is below offset '.$this->offset);
@@ -39,6 +64,8 @@ class LimitIterator implements OuterIterator
 		}
 	}
 
+    /** Rewind to offset specified in constructor
+     */
 	function rewind()
 	{
 		$this->it->rewind();
@@ -46,24 +73,35 @@ class LimitIterator implements OuterIterator
 		$this->seek($this->offset);
 	}
 	
+	/** @return whether iterator is valid
+	 */
 	function valid() {
 		return ($this->count == -1 || $this->pos < $this->offset + $this->count)
 			 && $this->it->valid();
 	}
 	
+	/** @return current key
+	 */
 	function key() {
 		return $this->it->key();
 	}
 
+	/** @return current element
+	 */
 	function current() {
 		return $this->it->current();
 	}
 
+	/** Forward to nect element
+	 */
 	function next() {
 		$this->it->next();
 		$this->pos++;
 	}
 
+	/** @return current position relative to zero (not to offset specified in 
+	 *          constructor).
+	 */
 	function getPosition() {
 		return $this->pos;
 	}
diff --git a/ext/spl/internal/outeriterator.inc b/ext/spl/internal/outeriterator.inc
index 0bfad6a589..712212aba3 100755
--- a/ext/spl/internal/outeriterator.inc
+++ b/ext/spl/internal/outeriterator.inc
@@ -1,11 +1,22 @@
 <?php
 
-/** \ingroup SPL
- * \brief Interface to access inner iterator of iterator wrappers
+/** @file outeriterator.inc
+ * @ingroup Internal
+ * @brief class OuterIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
+/**
+ * @brief   Interface to access the current inner iteraor of iterator wrappers
+ * @author  Marcus Boerger
+ * @version 1.0
  */
 interface OuterIterator extends Iterator
 {
-	/** \return inner iterator
+	/** @return inner iterator
 	 */
     function getInnerIterator();
 }
diff --git a/ext/spl/internal/parentiterator.inc b/ext/spl/internal/parentiterator.inc
index 4b758132ac..9d3c59d290 100755
--- a/ext/spl/internal/parentiterator.inc
+++ b/ext/spl/internal/parentiterator.inc
@@ -1,21 +1,48 @@
 <?php
 
+/** @file parentiterator.inc
+ * @ingroup Internal
+ * @brief class FilterIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
+/**
+ * @brief   Iterator to filter parents
+ * @author  Marcus Boerger
+ * @version 1.1
+ *
+ * This extended FilterIterator allows a recursive iteration using 
+ * RecursiveIteratorIterator that only shows those elements which have 
+ * children.
+ */
 class ParentIterator extends FilterIterator implements RecursiveIterator
 {
+	/** @param $it the RecursiveIterator to filter
+	 */
 	function __construct(RecursiveIterator $it)
 	{
 		parent::__construct($it);
 	}
+	
+	/** @return whetehr the current element has children
+	 */
 	function accept()
 	{
 		return $this->it->hasChildren();
 	}
 
+	/** @return whether the current element has children
+	 */
 	function hasChildren()
 	{
 		return $this->it->hasChildren();
 	}
 
+	/** @return the ParentIterator for the current elements children
+	 */
 	function getChildren()
 	{
 		return new ParentIterator($this->it->getChildren());
diff --git a/ext/spl/internal/recursiveiterator.inc b/ext/spl/internal/recursiveiterator.inc
index 63523ffad9..3bb0d8d0ff 100755
--- a/ext/spl/internal/recursiveiterator.inc
+++ b/ext/spl/internal/recursiveiterator.inc
@@ -1,8 +1,27 @@
 <?php
 
+/** @file recursiveiterator.inc
+ * @ingroup Internal
+ * @brief class RecursiveIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
+/**
+ * @brief   Interface for recursive iteration with RecursiveIteratorIterator
+ * @author  Marcus Boerger
+ * @version 1.0
+ */
 interface RecursiveIterator implements Iterator
 {
+	/** @return whether the current element has children
+	 */
 	function hasChildren();
+	
+	/** @return the sub iterator for the current element
+	 */
 	function getChildren();
 }
 
diff --git a/ext/spl/internal/recursiveiteratoriterator.inc b/ext/spl/internal/recursiveiteratoriterator.inc
index a04d860008..d2c9956030 100755
--- a/ext/spl/internal/recursiveiteratoriterator.inc
+++ b/ext/spl/internal/recursiveiteratoriterator.inc
@@ -1,9 +1,22 @@
 <?php
 
+/** @file recursiveiteratoriterator.inc
+ * @ingroup Internal
+ * @brief class RecursiveIteratorIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
+define('RIT_LEAVES_ONLY', 0);
+define('RIT_SELF_FIRST',  1);
+define('RIT_CHILD_FIRST', 2);
+
 /**
  * @brief   Iterates through recursive iterators
  * @author  Marcus Boerger
- * @version 1.0
+ * @version 1.1
  *
  */
 class RecursiveIteratorIterator implements OuterIterator
@@ -11,12 +24,21 @@ class RecursiveIteratorIterator implements OuterIterator
 	protected $ait = array();
 	protected $count = 0;
 
-	function __construct(RecursiveIterator $it)
+	/** Construct from RecursiveIterator
+	 *
+	 * @param it     RecursiveIterator to iterate
+	 * @param flags  Operation mode:
+	 *               - RIT_LEAVES_ONLY only show leaves
+	 *               - RIT_SELF_FIRST  show parents prior to their childs
+	 *               - RIT_CHILD_FIRST show all childs prior to their parent
+	 */
+	function __construct(RecursiveIterator $it, $flags)
 	{
 		$this->ait[0] = $it;
 	}
 
-
+	/** Rewind to top iterator as set in constructor
+	 */
 	function rewind()
 	{
 		while ($this->count) {
@@ -26,6 +48,8 @@ class RecursiveIteratorIterator implements OuterIterator
 		$this->ait[0]->recursed = false;
 	}
 	
+	/** @return whether iterator is valid
+	 */
 	function valid()
 	{
 		$count = $this->count;
@@ -39,18 +63,24 @@ class RecursiveIteratorIterator implements OuterIterator
 		return false;
 	}
 	
+	/** @reutrn current key
+	 */
 	function key()
 	{
 		$it = $this->ait[$this->count];
 		return $it->key();
 	}
 	
+	/** @return current element
+	 */
 	function current()
 	{
 		$it = $this->ait[$this->count];
 		return $it->current();
 	}
 	
+	/** Forward to next element
+	 */
 	function next()
 	{
 		while ($this->count) {
@@ -83,7 +113,10 @@ class RecursiveIteratorIterator implements OuterIterator
 			}
 		}
 	}
-	
+
+	/** @return Sub Iterator at given level or if unspecified the current sub 
+	 *          Iterator
+	 */
 	function getSubIterator($level = NULL)
 	{
 		if (is_null($level)) {
@@ -100,6 +133,8 @@ class RecursiveIteratorIterator implements OuterIterator
 		return $this->it;
 	}
 
+	/** @return Current Depth (Number of parents)
+	 */
 	function getDepth()
 	{
 		return $this->level;
diff --git a/ext/spl/internal/seekableiterator.inc b/ext/spl/internal/seekableiterator.inc
index 3012155771..2cc5331aa1 100755
--- a/ext/spl/internal/seekableiterator.inc
+++ b/ext/spl/internal/seekableiterator.inc
@@ -1,6 +1,17 @@
 <?php
 
-/** \brief seekable iterator
+/** @file seekableiterator.inc
+ * @ingroup Internal
+ * @brief class SeekableIterator
+ * @author  Marcus Boerger
+ * @date    2003 - 2004
+ *
+ * SPL - Standard PHP Library
+ */
+
+/** @brief seekable iterator
+ * @author  Marcus Boerger
+ * @version 1.0
  *
  * Turns a normal iterator ino a seekable iterator. When there is a way
  * to seek on an iterator LimitIterator can use this to efficiently rewind
-- 
2.50.1