core/lib/Drupal/Core/Cache/Cacheability.php | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/core/lib/Drupal/Core/Cache/Cacheability.php b/core/lib/Drupal/Core/Cache/Cacheability.php
index 0a782f9..df01e78 100644
--- a/core/lib/Drupal/Core/Cache/Cacheability.php
+++ b/core/lib/Drupal/Core/Cache/Cacheability.php
@@ -1,16 +1,29 @@
 <?php
 /**
  * @file
- * Contains \Drupal\Core\Cache\CacheableMetadata.
+ * Contains \Drupal\Core\Cache\Cacheability.
  */
 
 namespace Drupal\Core\Cache;
 
 /**
- * Defines a generic class for passing cacheability metadata.
+ * Value object to pass around and do calculations with cacheability metadata.
  *
- * @ingroup cache
+ * Just like the output of a computation depends on all inputs, the cacheability
+ * of the output also depends on the cacheability of all inputs.
+ *
+ * The main purpose of this value object then, is computing that combined
+ * cacheability of the (CacheableDependencyInterface) objects that were the
+ * inputs of a computation. Access results, Entities, Config, Contexts and so on
+ * all provide cacheability metadata. But one cannot just perform operations on
+ * for example entities and access results; they are independent, decoupled
+ * concepts. That is where this value object comes in. The ::createFromObject()
+ * method allows you to extract just the cacheability metadata of any of those
+ * objects and then combine their cacheability metadata.
  *
+ * @see \Drupal\Core\Cache\CacheableDependencyInterface
+ *
+ * @ingroup cache
  */
 class Cacheability implements RefinableCacheableDependencyInterface {