From 7cf8e2cf1ce909e1d8808e3357f66e3c11275365 Mon Sep 17 00:00:00 2001
From: Jose Lorenzo Rodriguez <jose.zap@gmail.com>
Date: Sun, 28 Jun 2015 16:01:37 +0200
Subject: [PATCH] Documenting Table::loadInto()

---
 src/ORM/Table.php | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/src/ORM/Table.php b/src/ORM/Table.php
index 7e6fd7a4709..ee8a2a86d77 100644
--- a/src/ORM/Table.php
+++ b/src/ORM/Table.php
@@ -2181,9 +2181,39 @@ public function buildRules(RulesChecker $rules)
         return $rules;
     }
 
-    public function loadInto($objects, array $contain)
+    /**
+     * Loads the specified associations in the passed entity or list of entities
+     * by executing extra queries in the database and merging the results in the
+     * appropriate properties.
+     *
+     * ### Example:
+     *
+     * ```
+     * $user = $usersTable->get(1);
+     * $user = $usersTable->loadInto($user, ['Articles.Tags', 'Articles.Comments']);
+     * echo $user->articles[0]->title;
+     * ```
+     *
+     * You can also load associations for multiple entities at once
+     *
+     * ### Example:
+     *
+     * ```
+     * $users = $usersTable->find()->where([...])->toList();
+     * $users = $usersTable->loadInto($users, ['Articles.Tags', 'Articles.Comments']);
+     * echo $user[1]->articles[0]->title;
+     * ```
+     *
+     * The properties for the associations to be loaded will be overwritten on each entity.
+     *
+     * @param Cake\Datasource\EntityInterface|array $entities a single entity or list of entities
+     * @param array $contain A `contain()` compatible array.
+     * @see Cake\ORM\Query\contain()
+     * @return Cake\Datasource\EntityInterface|array
+     */
+    public function loadInto($entities, array $contain)
     {
-        return (new LazyEagerLoader)->loadInto($objects, $contain, $this);
+        return (new LazyEagerLoader)->loadInto($entities, $contain, $this);
     }
 
     /**