diff --git a/core/modules/system/theme.api.php b/core/modules/system/theme.api.php
index b88f740..fde6471 100644
--- a/core/modules/system/theme.api.php
+++ b/core/modules/system/theme.api.php
@@ -162,7 +162,6 @@
  * removing them).
  *
  * @section assets Assets
- *
  * We can distinguish between three types of assets:
  * 1. unconditional page-level assets (loaded on all pages where the theme is in
  *    use): these are defined in the theme's *.info.yml file.
@@ -287,9 +286,61 @@
  * properties. Look through implementations of hook_element_info() to discover
  * elements defined this way.
  *
- * @section sec_attached Attaching libraries in render arrays
- *
+ * @section sec_caching Caching
+ * The Drupal rendering process has the ability to cache rendered output at any
+ * level in a render array hierarchy. This allows expensive calculations to be
+ * done infrequently, and speeds up page loading. See the
+ * @link cache Cache API topic @endlink for general information about the cache
+ * system.
+ *
+ * In order to make caching possible, the following information needs to be
+ * present:
+ * - Cache keys: Identifiers for cacheable portions of render arrays. These
+ *   should be created and added for portions of a render array that
+ *   involve expensive calculations in the rendering process.
+ * - Cache contexts: Contexts that may affect rendering, such as user role,
+ *   language, and request parameters. This can be omitted.
+ * - Cache tags: Tags for data that rendering depends on, such as for
+ *   individual nodes or user accounts, so that when these change the cache
+ *   can be automatically invalidated. If the data consists of entities, you
+ *   can use \Drupal\Core\Entity\EntityInterface::getCacheTags() to generate
+ *   appropriate tags; configuration objects have a similar method.
+ *
+ * Cache information is provided in the #cache property in a render array. In
+ * this property, supply the cache contexts and tags; the cache keys are
+ * generated automatically, and the cache contexts and tags will be propagated
+ * up the render array hierarchy to determine cacheabilty for containing render
+ * array sections. At the page level, you'll see X-Drupal-Cache-Contexts and
+ * X-Drupal-Cache-Tags in the HTML page header.
+ *
+ * Here is an annotated example, where a welcome message is generated:
+ * @code
+ * $config = \Drupal::config('system.site');
+ * $current_user = \Drupal::currentUser();
+ *
+ * $build = [
+ *   '#prefix' => '<aside>',
+ *   '#markup' => t('Hi, %name, welcome back to @site!', [
+ *     '%name' => $current_user->getUsername(),
+ *     '@site' => $config->get('name'),
+ *   ]),
+ *   '#suffix' => '</aside>',
+ *   '#cache' => [
+ *     // The message is specific to each user.
+ *     'contexts' => [
+ *       'user',
+ *     ],
+ *     // The cache should be invalidated when the user entity changes, or
+ *     // the system.site configuration changes.
+ *     'tags' => \Drupal\Core\Cache\Cache::mergeTags(
+ *       $config->getCacheTags(),
+ *       \Drupal\user\Entity\User::load($current_user->id())->getCacheTags()
+ *     ),
+ *   ],
+ * ];
+ * @endcode
  *
+ * @section sec_attached Attaching libraries in render arrays
  * Libraries, JavaScript settings, feeds, HTML <head> tags and HTML <head> links
  * are attached to elements using the #attached property. The #attached property
  * is an associative array, where the keys are the attachment types and the
@@ -303,14 +354,13 @@
  * values. Example:
  * @code
  * $build['#attached']['library'][] = 'core/jquery';
- * $build['#attached']['drupalSettings']['foo] = 'bar';
+ * $build['#attached']['drupalSettings']['foo'] = 'bar';
  * $build['#attached']['feed'][] = ['aggregator/rss', $this->t('Feed title')];
  * @endcode
  *
  * See drupal_process_attached() for additional information.
  *
  * @section render_pipeline The Render Pipeline (or: how Drupal renders pages)
- *
  * First, you need to know the general routing concepts: please read
  * @ref sec_controller first.
  *
@@ -382,7 +432,6 @@
  * when an error occurs, a simpler HTML page renderer is used for rendering
  * these bare pages: \Drupal\Core\Render\BareHtmlPageRenderer
  *
- *
  * @see themeable
  *
  * @}