[#2570593]: Improve docs on EntityStorageBase::postLoad() to explain the...

[#2570593]: Improve docs on EntityStorageBase::postLoad() to explain the special-case on how the entities array works.

core/lib/Drupal/Core/Entity/EntityStorageBase.php

@@ -357,6 +357,11 @@ protected function preLoad(array &$ids = NULL) {
   /**
    * Attaches data to entities upon loading.
    *
+   * If there are multiple bundle classes involved, each one gets a sub array
+   * with only the entities of the same bundle. If there's only a single bundle,
+   * the entity's postLoad() method will get a copy of the original $entities
+   * array.
+   *
    * @param array $entities
    *   Associative array of query results, keyed on the entity ID.
    */
@@ -365,10 +370,11 @@ protected function postLoad(array &$entities) {
 
     // Invoke entity class specific postLoad() methods. If there's only a single
     // class involved, we want to pass in the original $entities array. For
-    // example, \Drupal\user\Entity\Role::postLoad() sorts the array to enforce
-    // role weights. We have to let it manipulate the final array, not a
-    // subarray. However if there are multiple bundle classes involved, we only
-    // want to pass each one the entities that match.
+    // example, to provide backwards compatibility with the legacy behavior of
+    // the deprecated user_roles() method, \Drupal\user\Entity\Role::postLoad()
+    // sorts the array to enforce role weights. We have to let it manipulate the
+    // final array, not a subarray. However if there are multiple bundle classes
+    // involved, we only want to pass each one the entities that match.
     if (count($entities_by_class) === 1) {
       $entity_class = array_key_first($entities_by_class);
       $entity_class::postLoad($this, $entities);