diff --git a/core/lib/Drupal/Core/TypedData/TypedDataManager.php b/core/lib/Drupal/Core/TypedData/TypedDataManager.php
index 7c1d783..a72758d 100644
--- a/core/lib/Drupal/Core/TypedData/TypedDataManager.php
+++ b/core/lib/Drupal/Core/TypedData/TypedDataManager.php
@@ -416,20 +416,24 @@ public function clearCachedDefinitions() {
   }
 
   /**
-   * Gets the canonical representation of some data.
-   *
-   * The Typed Object often wraps the canonical representation of the
-   * data, while in other cases the Typed Object itself represents the main API
-   * and thus the canonical representation of the data. E.g., primitive values
-   * or entity objects are wrapped by Typed Objects, while field items and their
-   * lists use an object directly implemented the TypedDataInterface as
-   * canonical representation.
+   * Gets the canonical representation of a TypedData object.
    *
    * The canonical representation is typically used when data is passed on to
-   * other code components. E.g. when Typed Data is validated the canonical
-   * representation is passed on to constraint validators, such that
-   * entity objects get passed unwrapped and fields stay objects (which directly
-   * implemented TypedDataInterface).
+   * other code components. In many use cases, the TypedData object is mostly
+   * unified adapter wrapping a primary value (e.g. a string, an entity...)
+   * which is the canonical representation that consuming code like constraint
+   * validators are really interested in. For some APIs, though, the domain
+   * object (e.g. Field API's FieldItem and FieldItemList) directly implements
+   * TypedDataInterface, and the canonical representation is thus the data
+   * object itself.
+   *
+   * When a TypedData object gets validated, for example, its canonical
+   * representation is passed on to constraint validators, which thus receive
+   * an Entity unwrapped, but a FieldItem as is.
+   *
+   * Data types specify whether their data objects need unwrapping by using the
+   * 'unwrap_for_canonical_representation' property in the data definition
+   * (defaults to TRUE).
    *
    * @param \Drupal\Core\TypedData\TypedDataInterface $data
    *   The data.