.../HtmlResponsePlaceholderStrategySubscriber.php      |  4 ++--
 .../Placeholder/PlaceholderStrategyInterface.php       | 12 ++++++++----
 .../Render/Placeholder/PlaceholderStrategyManager.php  | 18 +++++++++---------
 3 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/core/lib/Drupal/Core/EventSubscriber/HtmlResponsePlaceholderStrategySubscriber.php b/core/lib/Drupal/Core/EventSubscriber/HtmlResponsePlaceholderStrategySubscriber.php
index 9953f83..147d51f 100644
--- a/core/lib/Drupal/Core/EventSubscriber/HtmlResponsePlaceholderStrategySubscriber.php
+++ b/core/lib/Drupal/Core/EventSubscriber/HtmlResponsePlaceholderStrategySubscriber.php
@@ -14,7 +14,7 @@
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
- * HTML Response subscriber to handle placeholder strategies.
+ * HTML response subscriber to allow for different  placeholder strategies.
  */
 class HtmlResponsePlaceholderStrategySubscriber implements EventSubscriberInterface {
 
@@ -36,7 +36,7 @@ public function __construct(PlaceholderStrategyInterface $placeholder_strategy_m
   }
 
   /**
-   * Processes placeholders for HtmlResponse responses.
+   * Processes placeholders for HTML responses.
    *
    * @param \Symfony\Component\HttpKernel\Event\FilterResponseEvent $event
    *   The event to process.
diff --git a/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyInterface.php b/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyInterface.php
index 8f10822..b6474d2 100644
--- a/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyInterface.php
+++ b/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyInterface.php
@@ -16,11 +16,15 @@
    * Processes placeholders to render them with different strategies.
    *
    * @param array $placeholders
-   *   The placeholders to process keyed by $placeholder_id with the render
-   *   cache array as value.
+   *   The placeholders to process, with the keys being the markup for the
+   *   placeholders and the values the corresponding render array describing the
+   *   data to be rendered.
    *
-   * @return array $placeholders
-   *   The new values for the placeholders, keyed by $placeholder_id => $render_array.
+   * @return array
+   *   The resulting placeholders, with a subset of the keys of $placeholders
+   *   (and those being the markup for the placeholders) but with the
+   *   corresponding render array being potentially modified to render e.g. an
+   *   ESI or BigPipe placeholder.
    */
   public function processPlaceholders(array $placeholders);
 
diff --git a/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyManager.php b/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyManager.php
index bcb1a00..a553bff 100644
--- a/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyManager.php
+++ b/core/lib/Drupal/Core/Render/Placeholder/PlaceholderStrategyManager.php
@@ -7,25 +7,25 @@
 
 namespace Drupal\Core\Render\Placeholder;
 
-use Drupal\Core\Render\RendererInterface;
-
 /**
- * Provides a class which allows to render placeholders.
+ * Renders placeholders using different strategies depending on priorities.
  */
 class PlaceholderStrategyManager implements PlaceholderStrategyInterface {
 
   /**
-   * The placeholder strategy services.
+   * An ordered list of placeholder strategy services.
+   *
+   * Ordered according to service priority.
    *
-   * @var Drupal\Core\Render\Placeholder\PlaceholderStrategyInterface[]
+   * @var \Drupal\Core\Render\Placeholder\PlaceholderStrategyInterface[]
    */
   protected $placeholderStrategies;
 
   /**
-   * Adds a render strategy to process.
+   * Adds a placeholder strategy to use.
    *
-   * @param PlaceholderStrategyInterface $strategy
-   *   The strategy to add to the render strategies.
+   * @param \Drupal\Core\Render\Placeholder\PlaceholderStrategyInterface $strategy
+   *   The strategy to add to the placeholder strategies.
    */
   public function addPlaceholderStrategy(PlaceholderStrategyInterface $strategy) {
     $this->placeholderStrategies[] = $strategy;
@@ -46,7 +46,7 @@ public function processPlaceholders(array $placeholders) {
 
     $new_placeholders = [];
 
-    // Give each render strategy a chance to replace all not-yet replaced
+    // Give each placeholder strategy a chance to replace all not-yet replaced
     // placeholders. The order of placeholder strategies is well defined
     // and this uses a variation of the "chain of responsibility" design pattern.
     foreach ($this->placeholderStrategies as $strategy) {