core/lib/Drupal/Core/Render/PlaceholderGenerator.php          | 6 +++---
 core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php | 5 +++++
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/core/lib/Drupal/Core/Render/PlaceholderGenerator.php b/core/lib/Drupal/Core/Render/PlaceholderGenerator.php
index a6c4a23..442ad6b 100644
--- a/core/lib/Drupal/Core/Render/PlaceholderGenerator.php
+++ b/core/lib/Drupal/Core/Render/PlaceholderGenerator.php
@@ -49,19 +49,19 @@ public function canCreatePlaceholder(array $element) {
    * {@inheritdoc}
    */
   public function shouldAutomaticallyPlaceholder(array $element) {
+    // Auto-placeholder if the max-age, cache context or cache tag is specified
+    // in the auto-placeholder conditions in the 'renderer.config' container
+    // parameter.
     $conditions = $this->rendererConfig['auto_placeholder_conditions'];
 
-    // Auto-placeholder if max-age is at or below the configured threshold.
     if (isset($element['#cache']['max-age']) && $element['#cache']['max-age'] !== Cache::PERMANENT && $element['#cache']['max-age'] <= $conditions['max-age']) {
       return TRUE;
     }
 
-    // Auto-placeholder if a high-cardinality cache context is set.
     if (isset($element['#cache']['contexts']) && array_intersect($element['#cache']['contexts'], $conditions['contexts'])) {
       return TRUE;
     }
 
-    // Auto-placeholder if a high-invalidation frequency cache tag is set.
     if (isset($element['#cache']['tags']) && array_intersect($element['#cache']['tags'], $conditions['tags'])) {
       return TRUE;
     }
diff --git a/core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php b/core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php
index 89802a2..224bcbf 100644
--- a/core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php
+++ b/core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php
@@ -35,6 +35,11 @@ public function canCreatePlaceholder(array $element);
   /**
    * Whether the given render array should be automatically placeholdered.
    *
+   * The render array should be placeholdered if its cacheability either has a
+   * cache context with too high cardinality, a cache tag with a too high
+   * invalidation rate, or a max-age that is too low. Either of these would make
+   * caching ineffective, and thus we choose to placeholder instead.
+   *
    * @param array $element
    *   The render array whose cacheability to analyze.
    *