From 1ae0413f5a96424b5f65b6b87c431a08e5c283ed Mon Sep 17 00:00:00 2001
From: Jose Lorenzo Rodriguez <jose.zap@gmail.com>
Date: Tue, 20 Aug 2013 23:36:40 +0200
Subject: [PATCH] adding doc blocks for new finders

---
 lib/Cake/ORM/Table.php                   | 35 ++++++++++++++++++++++--
 lib/Cake/Test/TestCase/ORM/TableTest.php |  5 ++++
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/lib/Cake/ORM/Table.php b/lib/Cake/ORM/Table.php
index 41ad48055d5..f1824037f78 100644
--- a/lib/Cake/ORM/Table.php
+++ b/lib/Cake/ORM/Table.php
@@ -513,8 +513,7 @@ public function find($type, $options = []) {
 	}
 
 /**
- * Applies the options required to find all records on this table based
- * on the passed options.
+ * Returns the query as passed
  *
  * @param \Cake\ORM\Query $query
  * @param array $options
@@ -524,6 +523,27 @@ public function findAll(Query $query, array $options = []) {
 		return $query;
 	}
 
+/**
+ * Sets up a query object so results appear as an indexed array, useful for any
+ * place where you would want a list such as for populating input select boxes.
+ *
+ * When calling this finder, the fields passed are used to determine what should
+ * be used as the array key, value and optionally what to group the results by.
+ * By default the primary key for the model is used for the key, and the display
+ * field.
+ *
+ * The results of this finder will be in the following form:
+ *
+ *	[
+ *		1 => 'value for id 1',
+ *		2 => 'value for id 2',
+ *		4 => 'value for id 4'
+ *	]
+ *
+ * @param \Cake\ORM\Query $query
+ * @param array $options
+ * @return \Cake\ORM\Query
+ */
 	public function findList(Query $query, array $options = []) {
 		$mapper = function($key, $row, $mr) use (&$columns) {
 			if (empty($columns)) {
@@ -551,6 +571,17 @@ public function findList(Query $query, array $options = []) {
 		return $query->mapReduce($mapper, $reducer);
 	}
 
+/**
+ * Results for this finder will be a nested array, and is appropriate if you want
+ * to use the parent_id field of your model data to build nested results.
+ *
+ * Values belonging to a parent row based on their parent_id value will be
+ * recursively nested inside the parent row values using the `children` property
+ *
+ * @param \Cake\ORM\Query $query
+ * @param array $options
+ * @return \Cake\ORM\Query
+ */
 	public function findThreaded(Query $query, array $options = []) {
 		$parents = [];
 		$mapper = function($key, $row, $mr) use (&$parents) {
diff --git a/lib/Cake/Test/TestCase/ORM/TableTest.php b/lib/Cake/Test/TestCase/ORM/TableTest.php
index b937fa682f2..21573785e3b 100644
--- a/lib/Cake/Test/TestCase/ORM/TableTest.php
+++ b/lib/Cake/Test/TestCase/ORM/TableTest.php
@@ -539,6 +539,11 @@ public function testFindList() {
 		$this->assertSame($expected, $query->toArray());
 	}
 
+/**
+ * Tests find('threaded')
+ *
+ * @return void
+ */
 	public function testFindThreaded() {
 		$table = new Table(['table' => 'categories', 'connection' => $this->connection]);
 		$expected = [