Что именно возвращает PHP SPL RecursiveIterator::getChildren()?

Я узнаю о стандартной библиотеке PHP Маркуса Бергера (SPL).

Я реализовал свой собственный RecursiveIterator, который по наследству реализует интерфейс Iterator. Он также реализует Countable.

Меня смущает current(), getChildren() и имеет дочерние методы. Это задокументировано по адресу: http://www.php.net/~helly/php/ext/spl/interfaceRecursiveIterator.html

If

• current() quote: 'Возвращает текущий элемент' и
• getChildren() возвращает, и я цитирую, «подитератор для текущего элемента».

Если, как в случае с current(), текущий элемент считается дочерним элементом текущего объекта.

Тогда, конечно же, в документации указано, что getChildren(), по сути, возвращает внуков рассматриваемого узла.

Отсюда и путаница.

<?php

/**
*@desc Represents a node within a hierarchy
*/
class RecursableCountableIterableNode implements RecursiveIterator, Countable
    {

    public $title;

    private $_componentsArray;
    private $_iteratorPosition;

    /**
    *@desc adds component
    */
    public function addComponent( 
            RecursableCountableIterableNode $incomingNodeObj 
            )
        {

        foreach ( $this->_componentsArray as $componentNodeObj )
            {
            if ( $incomingNodeObj === $componentNodeObj )
                {
                //its is already in there
                return;
                }
            }


        //add to the next element of the numerically indexed array
        $this->_componentsArray[] = $incomingNodeObj;       
        }



    /**
    * @desc RecursiveIterator Interface 
    */

    /**
    * @desc Implements the RecursiveIterator Interface 
    * @return boolean - Whether or not the node at the current element
    *  has children.
    * 
    * Note: This method does NOT count the children of this node, 
    * it counts the components of the node at the *current* element.
    * There is a subtle but important difference. 
    * It could have been better to name 
    * the interface method 'hasGrandChildren()'.
    */
    public function hasChildren()
        {
        return ( boolean ) count( $this->current() );
        }

    /**
    * @desc Gets the node of the current element which in effect is a container
    *  for childnodes. 
    * 
    * Note: According to the SPL, it does NOT get 'the child elements of
    *  the current node' ($this->_componentsArray) which was a surprise to me.
    * 
    * @return RecursableCountableIterableNode - the 
    * sub iterator for the current element 
    * 
    */
    public function getChildren()
        {
        return $this->current();
        }


    /**
    * @desc To adhere to countable interface.
    * @returns integer - The number of elements in the compondents array.
    */
    public function count()
        {
        return count( $this->_componentsArray );
        }


    /**
    * Iterator methods
    */

    /**
    * @desc Rewind the iterator to the first element.
    * @return void
    */
    public function rewind()
        {
        $this->_iteratorPosition = 0;
        }

    /**
    * @desc Return the current element.
    * @return RecursableCountableIterableNode
    */
    public function current()
        {
        return $this->_componentsArray[ $this->_iteratorPosition ];
        }

    /**
    * @desc Return the key of the current element.
    * @return integer
    */
    public function key()
        {
        return $this->_iteratorPosition;
        }

    /**
    * @desc Move forward to the next element.
    * @return void
    */
    public function next()
        {
        ++$this->_iteratorPosition;
        }

    /**
    * @desc Checks if current position has an element
    * @return boolean
    */
    public function valid()
        {
        return isset( $this->_componentsArray[ $this->_iteratorPosition ] );
        }   

    }

В приведенном выше классе getChildren() возвращает объект, реализующий RecursiveIterator и Countable. Потому что каждый объект RecursableCountableIterableNode содержит экземпляры других объектов RecursableCountableIterableNode. Я думаю, что это форма композитного шаблона.

Путем экспериментов мне удалось выполнить рекурсивную операцию на дереве, используя count() (в качестве конечного условия для выхода из рекурсивного процесса) и foreach для итерации по каждому дочернему узлу.

Что интересно, на самом деле неявная функция count выполняет операцию hasChildren, а конструкция foreach неявно выполняет операцию getChildren для выполнения рекурсивного обхода.

class NodeTreeProcessor
    {
    protected $output = '';

    public function doProcessingWithNode( 
            RecursableCountableIterableNode $treeNodeObj
            )
        {

        $this->output .= $treeNodeObj->title;

        //Base case that stops the recursion.
        if (!( count( $treeNodeObj ) > 0 ))
            {
            //it has no children
            return;
            }

        //Recursive case.
        foreach( $treeNodeObj as $childNode )
            {
            $this->doProcessingWithNode( $childNode );
            }       
        }
    }

Учитывая это, я думаю, что для того, чтобы быть практичным RecursiveIterator,

• getChildren действительно должен возвращать $this вместо узла в current(), и
• hasChildren действительно должен возвращать логический результат приведения count($this)

это правильно?

Спецификации говорят одно, что я понимаю буквально. Но мой практический опыт говорит о другом.