diff --git a/core/core.api.php b/core/core.api.php
index 9834d8c9..1790e5c 100755
--- a/core/core.api.php
+++ b/core/core.api.php
@@ -842,21 +842,23 @@
  * API provides this abstraction.
  *
  * @section sec_overview Overview
- * Each data type in the Typed Data API is a plugin class (annotatation class
+ * Each data type in the Typed Data API is a plugin class (annotation class
  * example: \Drupal\Core\TypedData\Annotation\DataType); these plugins are
  * managed by the typed_data_manager service. Each data object encapsulates a
  * single piece of data, provides access to the metadata, and provides
  * validation capability. Also, the typed data plugins have a shorthand
  * for easily accessing data values, described in @ref sec_tree.
  *
- * The metadata for the type is in a class called the definition class (for
- * example, \Drupal\Core\TypedData\DataDefinition). The name of the definition
- * class is contained in the plugin definition. A default can be set in the
- * $definition_class property of the annotation class. This can be overridden
- * in the definition_class property of the plugin annotation itself. Finally,
- * the plugin deriver can set it too. The metadata object provides information
- * about the data, such as the data type, whether it is translatable, the names
- * of its properties (for complex types), and who can access it.
+ * The metadata of a data object is defined by an object based on a class called
+ * the definition class (see \Drupal\Core\TypedData\DataDefinitionInterface).
+ * The class used can vary by data type and can be specified in the data type's
+ * plugin definition, while the default is set in the $definition_class property
+ * of the annotation class. The default class is
+ * \Drupal\Core\TypedData\DataDefinition. For data types provided by a plugin
+ * deriver, the plugin deriver can set the definition_class property too.
+ * The metadata object provides information about the data, such as the data
+ * type, whether it is translatable, the names of its properties
+ * (for complex types), and who can access it.
  *
  * See https://www.drupal.org/node/1794140 for more information about the Typed
  * Data API.
@@ -910,7 +912,7 @@
  * @section sec_tree Tree handling
  * Typed data allows you to use shorthand to get data values nested in the
  * implicit tree structure of the data. For example, to get the value from
- * an entity field item, you might just call
+ * an entity field item, the Entity Field API allows you to call
  * @code
  * $value = $entity->fieldName->propertyName;
  * @endcode
@@ -933,7 +935,8 @@
  *   on $property as well, so that all items will report the same langcode.
  * - When the value of $property is changed by calling $property->setValue(),
  *   $property->onChange() will fire, which in turn calls the parent object's
- *   onChange() method and so on.
+ *   onChange() method and so on. This allows parent objects to react upon
+ *   changes of contained properties or list items.
  *
  * @section sec_defining Defining data types
  * To define a new data type: