diff --git a/core/lib/Drupal/Core/Entity/RevisionableInterface.php b/core/lib/Drupal/Core/Entity/RevisionableInterface.php
index 14690e3c54..33acccae8c 100644
--- a/core/lib/Drupal/Core/Entity/RevisionableInterface.php
+++ b/core/lib/Drupal/Core/Entity/RevisionableInterface.php
@@ -4,6 +4,24 @@
 
 /**
  * Provides methods for an entity to support revisions.
+ *
+ * Classes implementing this interface do not necessarily support revisions.
+ *
+ * To detect whether an entity type supports revisions, call
+ * EntityTypeInterface::isRevisionable().
+ *
+ * Many entity interfaces are composed of numerous other interfaces such as this
+ * one, which allow implementations to pick and choose which features to.
+ * support through stub implementations of various interface methods. This means
+ * that even if an entity class implements RevisionableInterface, it might only
+ * have a stub implementation and not a functional one.
+ *
+ * Since Drupal's entity system is divided into a somewhat arbitrary entity
+ * class and it's corresponding more specific entity type class, we consult the
+ * type class to discover whether the entity class is intended to support
+ * revisions.
+ *
+ * @see \Drupal\Core\Entity\EntityTypeInterface::isRevisionable()
  */
 interface RevisionableInterface {
 
diff --git a/core/lib/Drupal/Core/TypedData/TranslatableInterface.php b/core/lib/Drupal/Core/TypedData/TranslatableInterface.php
index 5b57a8717f..771ff8f2c8 100644
--- a/core/lib/Drupal/Core/TypedData/TranslatableInterface.php
+++ b/core/lib/Drupal/Core/TypedData/TranslatableInterface.php
@@ -4,6 +4,24 @@
 
 /**
  * Interface for translatable data.
+ *
+ * Classes implementing this interface do not necessarily support translations.
+ *
+ * To detect whether an entity type supports revisions, call
+ * EntityTypeInterface::isTranslatable().
+ *
+ * Many entity interfaces are composed of numerous other interfaces such as this
+ * one, which allow implementations to pick and choose which features to.
+ * support through stub implementations of various interface methods. This means
+ * that even if an entity class implements TranslatableInterface, it might only
+ * have a stub implementation and not a functional one.
+ *
+ * Since Drupal's entity system is divided into a somewhat arbitrary entity
+ * class and it's corresponding more specific entity type class, we consult the
+ * type class to discover whether the entity class is intended to support
+ * translations.
+ *
+ * @see \Drupal\Core\Entity\EntityTypeInterface::isTranslatable()
  */
 interface TranslatableInterface {