core/modules/system/theme.api.php | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/core/modules/system/theme.api.php b/core/modules/system/theme.api.php
index 70f34ef..c0c160b 100644
--- a/core/modules/system/theme.api.php
+++ b/core/modules/system/theme.api.php
@@ -310,13 +310,27 @@
  *   Defaults to \Drupal\Core\Cache\Cache::PERMANENT (permanently cacheable).
  *
  * Cache information is provided in the #cache property in a render array. In
- * this property, always supply the cache contexts, tags and max-age. Cache keys
+ * this property, always supply the cache contexts, tags, and max-age if a
+ * render array varies by context, depends on some modifiable data or depends
+ * on information that's only valid for a limited time, respectively. Cache keys
  * should only be set on the portions of a render array that should be cached.
  * Contexts are automatically replaced with the value for the current request
  * (e.g. the current language) and combined with the keys to form a cache ID.
  * The cache contexts, tags and max-age will be propagated up the render array
  * hierarchy to determine cacheability for containing render array sections.
  *
+ * @code
+ * $build = [
+ *   …,
+ *   '#cache' => [
+ *     'keys' => ['entity_view', 'node', $node->id()],
+ *     'contexts' => ['language'],
+ *     'tags' => ['node:' . $node->id()],
+ *     'max-age' => Cache::PERMANENT,
+ *   ],
+ * ];
+ * @endcode
+ *
  * At the response level, you'll see X-Drupal-Cache-Contexts and
  * X-Drupal-Cache-Tags headers.
  *