diff --git a/core/lib/Drupal/Core/Entity/EntityTypeManagerInterface.php b/core/lib/Drupal/Core/Entity/EntityTypeManagerInterface.php
index 2a7a317..b9721a2 100644
--- a/core/lib/Drupal/Core/Entity/EntityTypeManagerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityTypeManagerInterface.php
@@ -95,6 +95,13 @@ public function hasHandler($entity_type, $handler_type);
   /**
    * Creates a new handler instance for a entity type and handler type.
    *
+   * Entity handlers are instantiated once per entity type and then cached
+   * in the entity type manager, and so subsequent calls to getHandler() for
+   * a particular entity type and handler type will return the same object.
+   * This means that properties on a handler may be used as a static cache,
+   * although care must be taken with any data that is specific to a
+   * particular entity.
+   *
    * @param string $entity_type
    *   The entity type for this handler.
    * @param string $handler_type