From f685f49410ed597cd389e4d992de1289da0c2028 Mon Sep 17 00:00:00 2001
From: Jose Lorenzo Rodriguez <jose.zap@gmail.com>
Date: Sun, 19 Jan 2014 15:13:16 +0100
Subject: [PATCH] Improving docs for find('list')

---
 src/ORM/Table.php | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/src/ORM/Table.php b/src/ORM/Table.php
index e5e76699cc8..4984f95a4c4 100644
--- a/src/ORM/Table.php
+++ b/src/ORM/Table.php
@@ -727,11 +727,47 @@ public function findAll(Query $query, array $options = []) {
  *
  * 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'
+ * ]
+ * }}}
+ *
+ * You can specify which property will be used as the key and which as value
+ * by using the `$options` array, when not specified, it will use the results
+ * of calling `primaryKey` and `displayField` respectively in this table:
+ *
+ * {{{
+ * $table->find('list', [
+ *	'idField' => 'name',
+ *	'valueField' => 'age'
+ * ]);
+ * }}}
+ *
+ * Results can be put together in bigger groups when they share a property, you
+ * can customize the property to use for grouping by setting `groupField`:
+ *
+ * {{{
+ * $table->find('list', [
+ *	'groupField' => 'category_id',
+ * ]);
+ * }}}
+ *
+ * When using a `groupField` results will be returned in this format:
+ *
+ * {{{
+ * [
+ *	'group_1' => [
  *		1 => 'value for id 1',
  *		2 => 'value for id 2',
+ *	]
+ *	'group_2' => [
  *		4 => 'value for id 4'
  *	]
+ * ]
+ * }}}
  *
  * @param \Cake\ORM\Query $query
  * @param array $options