Issue #3345197 by _shY, pradhumanjain2311, joachim, longwave:...

Issue #3345197 by _shY, pradhumanjain2311, joachim, longwave: loadByProperties() and buildPropertyQuery() should document that you can pass value arrays to get an IN query condition

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

@@ -585,8 +585,9 @@ public function restore(EntityInterface $entity) {
    * @param \Drupal\Core\Entity\Query\QueryInterface $entity_query
    *   EntityQuery instance.
    * @param array $values
-   *   An associative array of properties of the entity, where the keys are the
-   *   property names and the values are the values those properties must have.
+   *   An associative array where the keys are the property names and the
+   *   values are the values those properties must have. If a property takes
+   *   multiple values, passing an array of values will produce an IN condition.
    */
   protected function buildPropertyQuery(QueryInterface $entity_query, array $values) {
     foreach ($values as $name => $value) {

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

@@ -111,7 +111,8 @@ public function deleteRevision($revision_id);
    *
    * @param array $values
    *   An associative array where the keys are the property names and the
-   *   values are the values those properties must have.
+   *   values are the values those properties must have. If a property takes
+   *   multiple values, passing an array of values will produce an IN condition.
    *
    * @return \Drupal\Core\Entity\EntityInterface[]
    *   An array of entity objects indexed by their ids.