diff -u b/core/core.api.php b/core/core.api.php
--- b/core/core.api.php
+++ b/core/core.api.php
@@ -375,7 +375,7 @@
  * \Drupal\Core\Cache\CacheBackendInterface.
  *
  * The Cache API is used to store data that takes a long time to compute.
- * Caching can be permanent, temporary, or valid for a certain timespan, and
+ * Caching can either be permanent or valid only for a certain timespan, and
  * the cache can contain any type of data.
  *
  * To use the Cache API:
@@ -526,16 +526,17 @@
  *
  * @section context Cache contexts
  *
- * Some data that needs to be cached depends on contextual data, such as the
- * user roles of the logged-in user who is viewing a page, the language the page
- * is being rendered in, the theme being used, etc. The basic idea is that you
- * can cache several variations of the data, along with information about the
- * context each set of data applies to. The next time the data is needed, if the
- * context matches that for an existing cached data set, the cached data can be
- * reused; if no context matches, a new data set can be calculated and cached
- * for later use. See https://www.drupal.org/developing/api/8/cache/contexts for
- * more information on cache contexts, including a list of the contexts that
- * exist in Drupal core, and information on how to define your own contexts.
+ * Some computed data depends on contextual data, such as the user roles of the
+ * logged-in user who is viewing a page, the language the page is being rendered
+ * in, the theme being used, etc. When caching the output of such a calculation,
+ * you must cache each variation separately, along with information about which
+ * variation of the contextual data was used in the calculatation. The next time
+ * the computed data is needed, if the context matches that for an existing
+ * cached data set, the cached data can be reused; if no context matches, a new
+ * data set can be calculated and cached for later use. See
+ * https://www.drupal.org/developing/api/8/cache/contexts for more information
+ * on cache contexts, including a list of the contexts that exist in Drupal
+ * core, and information on how to define your own contexts.
  *
  * Typically, the cache context is specified as part of the #cache property
  * of a render array; see the Caching section of the