src/EntityHelperTrait.php               | 65 +++++++++++----------------------
 src/Plugin/Filter/EntityEmbedFilter.php |  2 +-
 src/Twig/EntityEmbedTwigExtension.php   |  2 +-
 3 files changed, 24 insertions(+), 45 deletions(-)

diff --git a/src/EntityHelperTrait.php b/src/EntityHelperTrait.php
index 7f93c36..1516507 100644
--- a/src/EntityHelperTrait.php
+++ b/src/EntityHelperTrait.php
@@ -7,7 +7,6 @@ use Drupal\Core\Entity\EntityInterface;
 use Drupal\Core\Entity\EntityManagerInterface;
 use Drupal\Core\Entity\EntityStorageException;
 use Drupal\Core\Extension\ModuleHandlerInterface;
-use Drupal\Core\Render\RendererInterface;
 use Drupal\entity_embed\EntityEmbedDisplay\EntityEmbedDisplayManager;
 
 /**
@@ -17,6 +16,11 @@ use Drupal\entity_embed\EntityEmbedDisplay\EntityEmbedDisplayManager;
  * classes that would implement ContainerInjectionInterface. Services registered
  * in the Container should not use this trait but inject the appropriate service
  * directly for easier testing.
+ *
+ * @todo this duplicates/wraps much of the Entity API. Is this really worth
+ * keeping? The downside is painfully illustrated: the documentation must be
+ * kept up to date with the actual API documentation… and that's not happening.
+ * This causes subtle bugs and makes maintenance harder.
  */
 trait EntityHelperTrait {
 
@@ -42,13 +46,6 @@ trait EntityHelperTrait {
   protected $displayPluginManager;
 
   /**
-   * The renderer.
-   *
-   * @var \Drupal\Core\Render\RendererInterface.
-   */
-  protected $renderer;
-
-  /**
    * Loads an entity from the database.
    *
    * @param string $entity_type
@@ -127,7 +124,7 @@ trait EntityHelperTrait {
   }
 
   /**
-   * Returns the render array for an entity.
+   * Builds the render array for the provided entity.
    *
    * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity to be rendered.
@@ -139,14 +136,19 @@ trait EntityHelperTrait {
    *
    * @return array
    *   A render array for the entity.
+   *
+   * @see \Drupal\Core\Entity\EntityViewBuilderInterface::view()
+   *
+   * @todo Note that the signature here does NOT match that of \Drupal\Core\Entity\EntityViewBuilderInterface::view(), which can lead to subtle bugs.
    */
-  protected function renderEntity(EntityInterface $entity, $view_mode, $langcode = NULL) {
-    $render_controller = $this->entityManager()->getViewBuilder($entity->getEntityTypeId());
-    return $render_controller->view($entity, $view_mode, $langcode);
+  protected function buildEntity(EntityInterface $entity, $view_mode, $langcode = NULL) {
+    return $this->entityManager()
+      ->getViewBuilder($entity->getEntityTypeId())
+      ->view($entity, $view_mode, $langcode);
   }
 
   /**
-   * Renders an embedded entity.
+   * Builds the render array for an embedded entity.
    *
    * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity to be rendered.
@@ -155,9 +157,11 @@ trait EntityHelperTrait {
    *   the embed HTML tag.
    *
    * @return array
-   *   A render array from entity_view().
+   *   A render array.
+   *
+   * @todo improve documentation
    */
-  protected function renderEntityEmbed(EntityInterface $entity, array $context = array()) {
+  protected function buildEntityEmbed(EntityInterface $entity, array $context = array()) {
     // Support the deprecated view-mode data attribute.
     if (isset($context['data-view-mode']) && !isset($context['data-entity-embed-display']) && !isset($context['data-entity-embed-settings'])) {
       $context['data-entity-embed-display'] = 'entity_reference:entity_reference_entity_view';
@@ -194,7 +198,7 @@ trait EntityHelperTrait {
       '#entity' => $entity,
       '#context' => $context,
     );
-    $build['entity'] = $this->renderEntityEmbedDisplayPlugin(
+    $build['entity'] = $this->buildEntityEmbedDisplayPlugin(
       $entity,
       $context['data-entity-embed-display'],
       $context['data-entity-embed-settings'],
@@ -223,7 +227,7 @@ trait EntityHelperTrait {
   }
 
   /**
-   * Renders an entity using an Entity Embed Display plugin.
+   * Builds the render array for an entity using an Entity Embed Display plugin.
    *
    * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity to be rendered.
@@ -238,7 +242,7 @@ trait EntityHelperTrait {
    * @return array
    *   A render array for the Entity Embed Display plugin.
    */
-  protected function renderEntityEmbedDisplayPlugin(EntityInterface $entity, $plugin_id, array $plugin_configuration = array(), array $context = array()) {
+  protected function buildEntityEmbedDisplayPlugin(EntityInterface $entity, $plugin_id, array $plugin_configuration = array(), array $context = array()) {
     // Build the Entity Embed Display plugin.
     /** @var \Drupal\entity_embed\EntityEmbedDisplay\EntityEmbedDisplayBase $display */
     $display = $this->displayPluginManager()->createInstance($plugin_id, $plugin_configuration);
@@ -332,29 +336,4 @@ trait EntityHelperTrait {
     return $this;
   }
 
-  /**
-   * Returns the renderer.
-   *
-   * @return \Drupal\Core\Render\RendererInterface
-   *   The renderer.
-   */
-  protected function renderer() {
-    if (!isset($this->renderer)) {
-      $this->renderer = \Drupal::service('renderer');
-    }
-    return $this->renderer;
-  }
-
-  /**
-   * Sets the renderer.
-   *
-   * @param \Drupal\Core\Render\RendererInterface $renderer
-   *   The renderer.
-   *
-   * @return self
-   */
-  public function setRenderer(RendererInterface $renderer) {
-    $this->renderer = $renderer;
-    return $this;
-  }
 }
diff --git a/src/Plugin/Filter/EntityEmbedFilter.php b/src/Plugin/Filter/EntityEmbedFilter.php
index 86666ca..e8059d5 100644
--- a/src/Plugin/Filter/EntityEmbedFilter.php
+++ b/src/Plugin/Filter/EntityEmbedFilter.php
@@ -108,7 +108,7 @@ class EntityEmbedFilter extends FilterBase implements ContainerFactoryPluginInte
 
             $context = $this->getNodeAttributesAsArray($node);
             $context += array('data-langcode' => $langcode);
-            $build = $this->renderEntityEmbed($entity, $context);
+            $build = $this->buildEntityEmbed($entity, $context);
             // We need to render the embedded entity:
             // - without replacing placeholders, so that the placeholders are
             //   only replaced at the last possible moment. Hence we cannot use
diff --git a/src/Twig/EntityEmbedTwigExtension.php b/src/Twig/EntityEmbedTwigExtension.php
index 9352e60..518088c 100644
--- a/src/Twig/EntityEmbedTwigExtension.php
+++ b/src/Twig/EntityEmbedTwigExtension.php
@@ -74,7 +74,7 @@ class EntityEmbedTwigExtension extends \Twig_Extension {
       'data-entity-embed-display' => $display_plugin,
       'data-entity-embed-settings' => $display_settings,
     );
-    return $this->renderEntityEmbed($entity, $context);
+    return $this->buildEntityEmbed($entity, $context);
   }
 
 }