Added some docs

src/Collection/Iterator/TreeIterator.php

@@ -14,8 +14,10 @@
  */
 namespace Cake\Collection\Iterator;
 
+use Cake\Collection\Collection;
 use Cake\Collection\CollectionTrait;
 use Cake\Collection\Iterator\TreePrinter;
+use RecursiveIterator;
 use RecursiveIteratorIterator;
 
 /**
@@ -27,17 +29,67 @@ class TreeIterator extends RecursiveIteratorIterator {
 
 	use CollectionTrait;
 
+/**
+ * The iteration mode
+ *
+ * @car integer
+ */
 	protected $_mode;
 
-	public function __construct($items, $mode = RecursiveIteratorIterator::LEAVES_ONLY, $flags = 0) {
+/**
+ * Constructor
+ *
+ * @param RecursiveIterator $items The iterator to flatten
+ * @param integer $mode
+ * @param integer $flags
+ */
+	public function __construct(RecursiveIterator $items, $mode = RecursiveIteratorIterator::SELF_FIRST, $flags = 0) {
 		parent::__construct($items, $mode, $flags);
 		$this->_mode = $mode;
 	}
 
+/**
+ * Returns another iterator which will return the values ready to be displayed
+ * to a user. It does so by extracting one property from each of the elements
+ * and prefixing it with a spacer so that the relative position in the tree
+ * can be visualized.
+ *
+ * Both $valuePath and $keyPath can be a string with a property name to extract
+ * or a dot separated path of properties that should be followed to get the last
+ * one in the path.
+ *
+ * Alternatively, $valuePath and $keyPath can be callable functions. They will get
+ * the current element as first parameter, the current iteration key as second
+ * parameter, and the iterator instance as third argument.
+ *
+ * ##Example
+ *
+ * {{{
+ *	$printer = (new Collection($treeStructure))->listNested()->printer('name');
+ * }}}
+ *
+ * Using a closure:
+ *
+ * {{{
+ *	$printer = (new Collection($treeStructure))
+ *		->listNested()
+ *		->printer(function($item, $key, $iterator) {
+ *			return $item->name;
+ *		});
+ * }}}
+ *
+ * @param string|callable $valuePath The property to extract or a callable to return
+ * the display value
+ * @param string|callable $keyPath The property to use as iteration key or a
+ * callable returning the key value.
+ * @param string $spacer The string to use for prefixing the values according to
+ * their depth in the array
+ * @return \Cake\Collection\Iterator\TreePrinter
+ */
 	public function printer($valuePath, $keyPath = null, $spacer = '__') {
 		if (!$keyPath) {
 			$counter = 0;
-			$keyPath = function() use ($counter) {
+			$keyPath = function() use (&$counter) {
 				return $counter++;
 			};
 		}

tests/TestCase/Collection/CollectionTest.php

@@ -938,20 +938,4 @@ class CollectionTest extends TestCase {
 		$this->assertEquals(range(1, 5), $collection->extract('id')->toArray(false));
 	}
 
-	public function testPrinter() {
-		$items = [
-			[
-				'id' => 1,
-				'name' => 'a',
-				'stuff' => [
-					['id' => 2, 'name' => 'b', 'stuff' => [['id' => 3, 'name' => 'c']]]
-				]
-			],
-			['id' => 4, 'name' => 'd', 'stuff' => [['id' => 5, 'name' => 'e']]]
-		];
-		$printer = (new Collection($items))->listNested('desc', 'stuff')->printer('name');
-		foreach ($printer as $k => $p) {
-			debug([$k => $p]);
-		}
-	}
 }