diff --git a/core/lib/Drupal/Core/Entity/ContentEntityBase.php b/core/lib/Drupal/Core/Entity/ContentEntityBase.php
index f236e2d..b215787 100644
--- a/core/lib/Drupal/Core/Entity/ContentEntityBase.php
+++ b/core/lib/Drupal/Core/Entity/ContentEntityBase.php
@@ -163,6 +163,8 @@
    * will be performed and the flag will be automatically set back to FALSE.
    *
    * @var bool
+   *
+   * @see \Drupal\Core\Entity\FieldableEntityInterface::setDeepSerialization()
    */
   protected $deepSerialization = FALSE;
 
@@ -474,7 +476,7 @@ public function __sleep() {
   /**
    * {@inheritdoc}
    */
-  public function setDeepSerialization($deep_serialization = TRUE) {
+  public function setDeepSerialization($deep_serialization) {
     $this->deepSerialization = $deep_serialization;
   }
 
diff --git a/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php b/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php
index e6ed455..0d6b210 100644
--- a/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php
@@ -239,9 +239,24 @@ public function setValidationRequired($required);
   /**
    * Flags the entity for deep serialization.
    *
-   * After calling this method and serializing the entity e.g.
-   * "serialize($entity);" a deep serialization will be performed and the flag
-   * will be automatically reset.
+   * When an entity is deeply serialized then its field items will have the
+   * opportunity to return also e.g. computed properties in order to serialize
+   * the whole entity structure and cover changes made on computed properties,
+   * which are not yet saved instead of only returning the metadata needed to
+   * re-compute/load the computed property. An example for this are entity
+   * reference fields, which during deep serialization will return their
+   * referenced entities. In this case not only the changes on the main entity
+   * will be serialized, but also the changes made on the referenced entities.
+   *
+   * Example usage:
+   * -Alter the title of a referenced entity and serialize the parent entity
+   * through deep serialization in order to serialize the change made on the
+   * referenced entity.
+   * @code
+   *   $entity->entity_reference_field->entity->setTitle('new entity reference title');
+   *   $entity->setDeepSerialization(TRUE);
+   *   serialize($entity);
+   * @endcode
    *
    * @param bool $deep_serialization
    *   TRUE if deep serialization should be performed when the entity is being
@@ -249,6 +264,6 @@ public function setValidationRequired($required);
    *
    * @return $this
    */
-  public function setDeepSerialization($deep_serialization = TRUE);
+  public function setDeepSerialization($deep_serialization);
 
 }
diff --git a/core/lib/Drupal/Core/Field/EntityReferenceFieldItemList.php b/core/lib/Drupal/Core/Field/EntityReferenceFieldItemList.php
index 11b66b8..6dc2ee6 100644
--- a/core/lib/Drupal/Core/Field/EntityReferenceFieldItemList.php
+++ b/core/lib/Drupal/Core/Field/EntityReferenceFieldItemList.php
@@ -18,7 +18,7 @@ public function getSerializationValue($deep_serialization) {
       $values = $this->getValue(TRUE);
       foreach ($values as $delta => $item_values) {
         if (isset($values[$delta]['entity']) && ($values[$delta]['entity'] instanceof FieldableEntityInterface)) {
-          $values[$delta]['entity']->setDeepSerialization();
+          $values[$delta]['entity']->setDeepSerialization(TRUE);
         }
       }
     }
diff --git a/core/lib/Drupal/Core/Field/FieldItemListInterface.php b/core/lib/Drupal/Core/Field/FieldItemListInterface.php
index 13c7545..fd5cd68 100644
--- a/core/lib/Drupal/Core/Field/FieldItemListInterface.php
+++ b/core/lib/Drupal/Core/Field/FieldItemListInterface.php
@@ -278,6 +278,10 @@ public function equals(FieldItemListInterface $list_to_compare);
    *   Whether a deep serialization is running.
    *
    * @return mixed
+   *   Depending on whether deep serialization is running or not the returned
+   *   value might be either the data value as returned by ::getValue() if deep
+   *   serialization is not running or additionally contain computed properties
+   *   next to the data values if deep serialization is running.
    */
   public function getSerializationValue($deep_serialization);
 
diff --git a/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php b/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php
index 19163aa..b156dff 100644
--- a/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php
+++ b/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php
@@ -213,7 +213,7 @@ public function getValue($include_computed = FALSE) {
 
     // If there is an unsaved entity, return it as part of the field item values
     // to ensure idempotency of getValue() / setValue().
-    if (($include_computed && !$this->isEmpty()) || $this->hasNewEntity()) {
+    if ($this->hasNewEntity() || ($include_computed && !$this->isEmpty())) {
       $values['entity'] = $this->entity;
     }
     return $values;