EntityStorageInterface::loadByProperties() needs to say what it returns when nothing found

Agreed, it looks like it returns an empty array if there aren't any matching entities.

EntityStorageInterface::loadMultiple() should also document that. And it would also probably be good if load() and loadRevision() documented that they return NULL if no matching entity is found.

I'll work on these documentation issues

Ok, I think I covered what you said before with this patch

Looks good!

Could you also do me a favor and fix a pet peeve: "id" is a psychological term (ego, supergo, id), whereas "ID" means "identifier". So:

+ *   An array of entity objects indexed by their ids. Returns an empty
+ *   array if no matching entities found.

should say "... by their IDs". I realize this was in the existing documentation, but it would be great to get fixed!

Also, in @return lines, if they do not already say "@return array", could you add the "array" there for ones that return an array?

And in

    * @return \Drupal\Core\Entity\EntityInterface
-   *   An entity object.
+   *   An entity object. NULL if no matching entity is found.
    */
   public function load($id);

The @return line should say "\Drupal\Core\Entity\EntityInterface|null", since NULL can be returned.

And... hmmm...

   * @return \Drupal\Core\Entity\EntityInterface|false
-   *   The specified entity revision or FALSE if not found.
+   *   The specified entity revision or NULL if not found.
    */
   public function loadRevision($revision_id);

It looks like we should check on that. I verified that load() does return NULL if no matching entity is found, but... let's see. It looks like it might return an explicit FALSE, or a NULL, or just not return anything, judging by the actual implementations. That is kind of a mess. We should file a separate issue for that, and take this change out of the patch. Sorry about the misdirection!
#2296115: Several entity loadRevision() methods do not obey the interface contract

@jhodgdon , Thanks for all the clarification ! do not worry at all about the misdirection, I've also updated the documentation patch accordingly with the changes you made in #2296115: Several entity loadRevision() methods do not obey the interface contract.

Hope this is OK now, if I missed something just let me know :)

RE #8 - you are right about returning NULL:
http://www.php.net/manual/en/functions.returning-values.php

Anyway... That aside, this patch:

The idea on the other issue is that entity revision loading would return NULL if there is no entity found, not FALSE. But anyway we should probably fix all revision-related docs on the other issue and take them out of this patch. I'll make a note there. Please remove revision stuff from this patch though. It will just conflict with the other issue, and be incorrect.

Also, on the loadUnchanged() method, in practice this calls the load() method, so the documentation there is incorrect about returning FALSE (it would return NULL if not found):

   * @return \Drupal\Core\Entity\EntityInterface
+   * @return \Drupal\Core\Entity\EntityInterface|false
    *   The unchanged entity, or FALSE if the entity cannot be loaded.
 

Gotcha, I've removed the changes to the doc for loadRevision, and corrected the one for loadUnchanged

This is related to revisions; we should remove from the patch too:

 * @param int $revision_id
  *   The id of the entity to load.
  *
- * @return \Drupal\Core\Entity\EntityInterface
+ * @return \Drupal\Core\Entity\EntityInterface|false
  *   The entity object, or FALSE if there is no entity with the given revision
  *   id.
  *

The rest looks good, thanks!

Sorry, missed that one :(

Looks good, thanks!

Committed f654024 and pushed to 8.x. Thanks!

diff --git a/core/includes/entity.inc b/core/includes/entity.inc
index 9e18b10..67b3738 100644
--- a/core/includes/entity.inc
+++ b/core/includes/entity.inc
@@ -213,8 +213,8 @@ function entity_load_multiple($entity_type, array $ids = NULL, $reset = FALSE) {
  *   values are the values those properties must have.
  *
  * @return array
- *   An array of entity objects indexed by their IDs. Returns an empty
- *   array if no matching entities found.
+ *   An array of entity objects indexed by their IDs. Returns an empty array if
+ *   no matching entities found.
  */
 function entity_load_multiple_by_properties($entity_type, array $values) {
   return \Drupal::entityManager()
diff --git a/core/lib/Drupal/Core/Entity/EntityStorageInterface.php b/core/lib/Drupal/Core/Entity/EntityStorageInterface.php
index 18f1e81..e91f04c 100644
--- a/core/lib/Drupal/Core/Entity/EntityStorageInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityStorageInterface.php
@@ -46,8 +46,8 @@ public function resetCache(array $ids = NULL);
    *   An array of entity IDs, or NULL to load all entities.
    *
    * @return array
-   *   An array of entity objects indexed by their IDs. Returns an empty
-   *   array if no matching entities found.
+   *   An array of entity objects indexed by their IDs. Returns an empty array
+   *   if no matching entities found.
    */
   public function loadMultiple(array $ids = NULL);
 

Reflowed the comments on commit.