diff --git a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
index 33ecdae..9f2186f 100644
--- a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\ContentEntityInterface.
+ * Contains \Drupal\Core\Entity\ContentEntityInterface.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/DatabaseStorageController.php b/core/lib/Drupal/Core/Entity/DatabaseStorageController.php
index a9f08ab..3c3868f 100644
--- a/core/lib/Drupal/Core/Entity/DatabaseStorageController.php
+++ b/core/lib/Drupal/Core/Entity/DatabaseStorageController.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\DatabaseStorageController.
+ * Contains \Drupal\Core\Entity\DatabaseStorageController.
  */
 
 namespace Drupal\Core\Entity;
@@ -665,14 +665,14 @@ protected function invokeHook($hook, EntityInterface $entity) {
    * Implements Drupal\Core\Entity\EntityStorageControllerInterface::getFieldDefinitions().
    */
   public function getFieldDefinitions(array $constraints) {
-    // @todo: Add caching for $this->propertyInfo.
+    // @todo: Add caching for $this->entityFieldInfo.
     if (!isset($this->entityFieldInfo)) {
       $this->entityFieldInfo = array(
         'definitions' => $this->baseFieldDefinitions(),
-        // Contains definitions of optional (per-bundle) properties.
+        // Contains definitions of optional (per-bundle) fields.
         'optional' => array(),
-        // An array keyed by bundle name containing the names of the per-bundle
-        // properties.
+        // An array keyed by bundle name containing the optional fields added by
+        // the bundle.
         'bundle map' => array(),
       );
 
@@ -696,12 +696,12 @@ public function getFieldDefinitions(array $constraints) {
 
     $bundle = !empty($constraints['bundle']) ? $constraints['bundle'] : FALSE;
 
-    // Add in per-bundle properties.
+    // Add in per-bundle fields.
     if (!isset($this->fieldDefinitions[$bundle])) {
       $this->fieldDefinitions[$bundle] = $this->entityFieldInfo['definitions'];
 
-      if ($bundle && isset($this->entityFieldInfo['bundle map'][$constraints['bundle']])) {
-        $this->fieldDefinitions[$bundle] += array_intersect_key($this->entityFieldInfo['optional'], array_flip($this->entityFieldInfo['bundle map'][$constraints['bundle']]));
+      if ($bundle && isset($this->entityFieldInfo['bundle map'][$bundle])) {
+        $this->fieldDefinitions[$bundle] += array_intersect_key($this->entityFieldInfo['optional'], array_flip($this->entityFieldInfo['bundle map'][$bundle]));
       }
     }
     return $this->fieldDefinitions[$bundle];
diff --git a/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php b/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php
index 5b538c8..f7a031d 100644
--- a/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php
+++ b/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\DatabaseStorageControllerNG.
+ * Contains \Drupal\Core\Entity\DatabaseStorageControllerNG.
  */
 
 namespace Drupal\Core\Entity;
@@ -150,7 +150,9 @@ protected function mapFromStorageRecords(array $records, $load_revision = FALSE)
     foreach ($records as $id => $record) {
       $values = array();
       foreach ($record as $name => $value) {
-        // Avoid unnecessary array hierarchies to save memory.
+        // Skip the item delta and item value levels but let the field assign
+        // the value as suiting. This avoids unnecessary array hierarchies and
+        // saves memory here.
         $values[$name][LANGUAGE_DEFAULT] = $value;
       }
       $bundle = $this->bundleKey ? $record->{$this->bundleKey} : FALSE;
diff --git a/core/lib/Drupal/Core/Entity/Entity.php b/core/lib/Drupal/Core/Entity/Entity.php
index adbb047..177e943 100644
--- a/core/lib/Drupal/Core/Entity/Entity.php
+++ b/core/lib/Drupal/Core/Entity/Entity.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Entity.
+ * Contains \Drupal\Core\Entity\Entity.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityAccessController.php b/core/lib/Drupal/Core/Entity/EntityAccessController.php
index 2f13110..c3058f9 100644
--- a/core/lib/Drupal/Core/Entity/EntityAccessController.php
+++ b/core/lib/Drupal/Core/Entity/EntityAccessController.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Contains Drupal\Core\Entity\EntityAccessController.
+ * Contains \Drupal\Core\Entity\EntityAccessController.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityAccessControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityAccessControllerInterface.php
index 5bbc996..a40477c 100644
--- a/core/lib/Drupal/Core/Entity/EntityAccessControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityAccessControllerInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Contains Drupal\Core\Entity\EntityAccessControllerInterface.
+ * Contains \Drupal\Core\Entity\EntityAccessControllerInterface.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityBCDecorator.php b/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
index 9f77649..75ba243 100644
--- a/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
+++ b/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
@@ -14,15 +14,17 @@
 /**
  * Implements a decorator providing backwards compatible entity field access.
  *
- * Allows using entities converted to the new Entity Field API with the Drupal 7
- * way of accessing fields or properties.
- *
- * Note: We access the protected 'values' and 'fields' properties of the entity
- * via the magic getter - which returns them by reference for us. We do so, as
- * providing references to this arrays makes $entity->values and $entity->fields
- * to references itself as well, which is problematic during __clone() (this is
- * something that would not be easy to fix as an unset() on the variable is
- * problematic with the magic getter/setter then).
+ * Allows using entities converted to the new Entity Field API with the previous
+ * way of accessing fields or properties, e.g. via the BC decorator you can do:
+ * @code
+ *   $node->title = $value;
+ *   $node->body[LANGUAGE_NONE][0]['value'] = $value;
+ * @endcode
+ * Without the BC decorator the same assignment would have to look like this:
+ * @code
+ *   $node->title->value = $value;
+ *   $node->body->value = $value;
+ * @endcode
  */
 class EntityBCDecorator implements IteratorAggregate, EntityInterface {
 
@@ -63,17 +65,32 @@ public function getBCEntity() {
    * Directly accesses the plain field values, as done in Drupal 7.
    */
   public function &__get($name) {
-    // Make sure $this->decorated->values reflects the latest values.
+    // We access the protected 'values' and 'fields' properties of the decorated
+    // entity via the magic getter - which returns them by reference for us. We
+    // do so, as providing references to this arrays would make $entity->values
+    // and $entity->fields to references itself, which is problematic during
+    // __clone() (this is something we cannot work-a-round easily as an unset()
+    // on the variable is problematic in conjunction with the magic
+    // getter/setter).
+
     if (!empty($this->decorated->fields[$name])) {
+      // Any field values set via the new Entity Field API will be stored inside
+      // the field objects managed by the entity, thus we need to ensure
+      // $this->decorated->values reflects the latest values first.
       foreach ($this->decorated->fields[$name] as $langcode => $field) {
         $this->decorated->values[$name][$langcode] = $field->getValue();
       }
-      // Values might be changed by reference, so remove the field object to
-      // avoid them becoming out of sync.
+      // The returned values might be changed by reference, so we need to remove
+      // the field object to avoid the field object and the value getting out of
+      // sync. That way, the next field object instantiated by EntityNG will
+      // receive the possibly updated value.
       unset($this->decorated->fields[$name]);
     }
-    // Allow accessing field values in entity default languages other than
+    // Allow accessing field values in entity default language other than
     // LANGUAGE_DEFAULT by mapping the values to LANGUAGE_DEFAULT.
+    // This is necessary as EntityNG does key values in default language always
+    // with LANGUAGE_DEFAULT while field API expects them to be keyed by
+    // langcode.
     $langcode = $this->decorated->language()->langcode;
     if ($langcode != LANGUAGE_DEFAULT && isset($this->decorated->values[$name][LANGUAGE_DEFAULT]) && !isset($this->decorated->values[$name][$langcode])) {
       $this->decorated->values[$name][$langcode] = &$this->decorated->values[$name][LANGUAGE_DEFAULT];
diff --git a/core/lib/Drupal/Core/Entity/EntityFormController.php b/core/lib/Drupal/Core/Entity/EntityFormController.php
index 4e0fc6a..9087812 100644
--- a/core/lib/Drupal/Core/Entity/EntityFormController.php
+++ b/core/lib/Drupal/Core/Entity/EntityFormController.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityFormController.
+ * Contains \Drupal\Core\Entity\EntityFormController.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityFormControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityFormControllerInterface.php
index fecb078..a42c750 100644
--- a/core/lib/Drupal/Core/Entity/EntityFormControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityFormControllerInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityFormControllerInterface.
+ * Contains \Drupal\Core\Entity\EntityFormControllerInterface.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityFormControllerNG.php b/core/lib/Drupal/Core/Entity/EntityFormControllerNG.php
index 51bc911..ac30d5c 100644
--- a/core/lib/Drupal/Core/Entity/EntityFormControllerNG.php
+++ b/core/lib/Drupal/Core/Entity/EntityFormControllerNG.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityFormControllerNG.
+ * Contains \Drupal\Core\Entity\EntityFormControllerNG.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityInterface.php b/core/lib/Drupal/Core/Entity/EntityInterface.php
index 94ecc3b..a435ddc 100644
--- a/core/lib/Drupal/Core/Entity/EntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityInterface.
+ * Contains \Drupal\Core\Entity\EntityInterface.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityListController.php b/core/lib/Drupal/Core/Entity/EntityListController.php
index 1fdb4ba..d0d88f2 100644
--- a/core/lib/Drupal/Core/Entity/EntityListController.php
+++ b/core/lib/Drupal/Core/Entity/EntityListController.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityListController.
+ * Contains \Drupal\Core\Entity\EntityListController.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php
index 85790c3..ec8bc7c 100644
--- a/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityListControllerInterface.
+ * Contains \Drupal\Core\Entity\EntityListControllerInterface.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityMalformedException.php b/core/lib/Drupal/Core/Entity/EntityMalformedException.php
index ae60cba..cc32796 100644
--- a/core/lib/Drupal/Core/Entity/EntityMalformedException.php
+++ b/core/lib/Drupal/Core/Entity/EntityMalformedException.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityMalformedException.
+ * Contains \Drupal\Core\Entity\EntityMalformedException.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityNG.php b/core/lib/Drupal/Core/Entity/EntityNG.php
index 7df5b1e..7216a71 100644
--- a/core/lib/Drupal/Core/Entity/EntityNG.php
+++ b/core/lib/Drupal/Core/Entity/EntityNG.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityNG.
+ * Contains \Drupal\Core\Entity\EntityNG.
  */
 
 namespace Drupal\Core\Entity;
@@ -66,7 +66,7 @@ class EntityNG extends Entity {
   /**
    * Local cache for field definitions.
    *
-   * @see self::getPropertyDefinitions()
+   * @see static::getPropertyDefinitions()
    *
    * @var array
    */
diff --git a/core/lib/Drupal/Core/Entity/EntityRenderController.php b/core/lib/Drupal/Core/Entity/EntityRenderController.php
index f942ae0..273127e 100644
--- a/core/lib/Drupal/Core/Entity/EntityRenderController.php
+++ b/core/lib/Drupal/Core/Entity/EntityRenderController.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityRenderController.
+ * Contains \Drupal\Core\Entity\EntityRenderController.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php
index c24ffaa..d74a2a7 100644
--- a/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityRenderControllerInterface.
+ * Contains \Drupal\Core\Entity\EntityRenderControllerInterface.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php
index f5a596d..ee0302d 100644
--- a/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityStorageControllerInterface.
+ * Contains \Drupal\Core\Entity\EntityStorageControllerInterface.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/EntityStorageException.php b/core/lib/Drupal/Core/Entity/EntityStorageException.php
index 53ff738..1798f72 100644
--- a/core/lib/Drupal/Core/Entity/EntityStorageException.php
+++ b/core/lib/Drupal/Core/Entity/EntityStorageException.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityStorageException.
+ * Contains \Drupal\Core\Entity\EntityStorageException.
  */
 
 namespace Drupal\Core\Entity;
diff --git a/core/lib/Drupal/Core/Entity/Field/FieldInterface.php b/core/lib/Drupal/Core/Entity/Field/FieldInterface.php
index 760f07a..6aae6f7 100644
--- a/core/lib/Drupal/Core/Entity/Field/FieldInterface.php
+++ b/core/lib/Drupal/Core/Entity/Field/FieldInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\FieldInterface.
+ * Contains \Drupal\Core\Entity\Field\FieldInterface.
  */
 
 namespace Drupal\Core\Entity\Field;
diff --git a/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php b/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php
index a1fdc6b..461464e 100644
--- a/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php
+++ b/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\FieldItemBase.
+ * Contains \Drupal\Core\Entity\Field\FieldItemBase.
  */
 
 namespace Drupal\Core\Entity\Field;
diff --git a/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php b/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php
index 2b94e7a..7749c50 100644
--- a/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php
+++ b/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\FieldItemInterface.
+ * Contains \Drupal\Core\Entity\Field\FieldItemInterface.
  */
 
 namespace Drupal\Core\Entity\Field;
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/BooleanItem.php b/core/lib/Drupal/Core/Entity/Field/Type/BooleanItem.php
index 39f61b5..c808b1b 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/BooleanItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/BooleanItem.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\BooleanItem.
+ * Contains \Drupal\Core\Entity\Field\Type\BooleanItem.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
@@ -17,7 +17,7 @@ class BooleanItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see BooleanItem::getPropertyDefinitions()
    *
    * @var array
    */
@@ -28,12 +28,12 @@ class BooleanItem extends FieldItemBase {
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['value'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['value'] = array(
         'type' => 'boolean',
         'label' => t('Boolean value'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/DateItem.php b/core/lib/Drupal/Core/Entity/Field/Type/DateItem.php
index b53b97f..d55ebe2 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/DateItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/DateItem.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\DateItem.
+ * Contains \Drupal\Core\Entity\Field\Type\DateItem.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
@@ -17,7 +17,7 @@ class DateItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see DateItem::getPropertyDefinitions()
    *
    * @var array
    */
@@ -28,12 +28,12 @@ class DateItem extends FieldItemBase {
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['value'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['value'] = array(
         'type' => 'date',
         'label' => t('Date value'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/EntityReferenceItem.php b/core/lib/Drupal/Core/Entity/Field/Type/EntityReferenceItem.php
index 6c4a6fc..270734c 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/EntityReferenceItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/EntityReferenceItem.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\EntityReferenceItem.
+ * Contains \Drupal\Core\Entity\Field\Type\EntityReferenceItem.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
@@ -21,7 +21,7 @@ class EntityReferenceItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see EntityReferenceItem::getPropertyDefinitions()
    *
    * @var array
    */
@@ -34,13 +34,13 @@ public function getPropertyDefinitions() {
     // Definitions vary by entity type, so key them by entity type.
     $entity_type = $this->definition['settings']['entity type'];
 
-    if (!isset(self::$propertyDefinitions[$entity_type])) {
-      self::$propertyDefinitions[$entity_type]['value'] = array(
+    if (!isset(static::$propertyDefinitions[$entity_type])) {
+      static::$propertyDefinitions[$entity_type]['value'] = array(
         // @todo: Lookup the entity type's ID data type and use it here.
         'type' => 'integer',
         'label' => t('Entity ID'),
       );
-      self::$propertyDefinitions[$entity_type]['entity'] = array(
+      static::$propertyDefinitions[$entity_type]['entity'] = array(
         'type' => 'entity',
         'constraints' => array(
           'entity type' => $entity_type,
@@ -53,7 +53,7 @@ public function getPropertyDefinitions() {
         'settings' => array('id source' => 'value'),
       );
     }
-    return self::$propertyDefinitions[$entity_type];
+    return static::$propertyDefinitions[$entity_type];
   }
 
   /**
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php b/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php
index b4fe089..9ca0f87 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Type\EntityTranslation.
+ * Contains \Drupal\Core\Entity\Type\EntityTranslation.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php b/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php
index ffc9fd1..6df8b2e 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\EntityWrapper.
+ * Contains \Drupal\Core\Entity\Field\Type\EntityWrapper.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/Field.php b/core/lib/Drupal/Core/Entity/Field/Type/Field.php
index 03d17e4..0a82cf7 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/Field.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/Field.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\Field.
+ * Contains \Drupal\Core\Entity\Field\Type\Field.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
@@ -111,7 +111,7 @@ public function setValue($values) {
   public function getString() {
     $strings = array();
     if (isset($this->list)) {
-      foreach ($this->list() as $item) {
+      foreach ($this->list as $item) {
         $strings[] = $item->getString();
       }
       return implode(', ', array_filter($strings));
@@ -277,9 +277,9 @@ public function isEmpty() {
    */
   public function __clone() {
     if (isset($this->list)) {
-      foreach ($this->list as $delta => $property) {
-        $this->list[$delta] = clone $property;
-        if ($property instanceof ContextAwareInterface) {
+      foreach ($this->list as $delta => $item) {
+        $this->list[$delta] = clone $item;
+        if ($item instanceof ContextAwareInterface) {
           $this->list[$delta]->setContext($delta, $this);
         }
       }
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/IntegerItem.php b/core/lib/Drupal/Core/Entity/Field/Type/IntegerItem.php
index 2d1585f..fe84eb7 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/IntegerItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/IntegerItem.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\IntegerItem.
+ * Contains \Drupal\Core\Entity\Field\Type\IntegerItem.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
@@ -17,7 +17,7 @@ class IntegerItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see IntegerItem::getPropertyDefinitions()
    *
    * @var array
    */
@@ -28,12 +28,12 @@ class IntegerItem extends FieldItemBase {
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['value'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['value'] = array(
         'type' => 'integer',
         'label' => t('Integer value'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/LanguageItem.php b/core/lib/Drupal/Core/Entity/Field/Type/LanguageItem.php
index a6e548e..2014556 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/LanguageItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/LanguageItem.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\LanguageItem.
+ * Contains \Drupal\Core\Entity\Field\Type\LanguageItem.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
@@ -18,7 +18,7 @@ class LanguageItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see LanguageItem::getPropertyDefinitions()
    *
    * @var array
    */
@@ -29,12 +29,12 @@ class LanguageItem extends FieldItemBase {
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['value'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['value'] = array(
         'type' => 'string',
         'label' => t('Language code'),
       );
-      self::$propertyDefinitions['language'] = array(
+      static::$propertyDefinitions['language'] = array(
         'type' => 'language',
         'label' => t('Language object'),
         // The language object is retrieved via the language code.
@@ -43,7 +43,7 @@ public function getPropertyDefinitions() {
         'settings' => array('langcode source' => 'value'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 
   /**
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/StringItem.php b/core/lib/Drupal/Core/Entity/Field/Type/StringItem.php
index 6d98a52..f967e62 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/StringItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/StringItem.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Field\Type\StringItem.
+ * Contains \Drupal\Core\Entity\Field\Type\StringItem.
  */
 
 namespace Drupal\Core\Entity\Field\Type;
@@ -17,7 +17,7 @@ class StringItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see StringItem::getPropertyDefinitions()
    *
    * @var array
    */
@@ -28,12 +28,12 @@ class StringItem extends FieldItemBase {
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['value'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['value'] = array(
         'type' => 'string',
         'label' => t('Text value'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }
diff --git a/core/lib/Drupal/Core/Entity/Query/ConditionBase.php b/core/lib/Drupal/Core/Entity/Query/ConditionBase.php
index 7a77580..3edaf9a 100644
--- a/core/lib/Drupal/Core/Entity/Query/ConditionBase.php
+++ b/core/lib/Drupal/Core/Entity/Query/ConditionBase.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Query\ConditionBase.
+ * Contains \Drupal\Core\Entity\Query\ConditionBase.
  */
 
 namespace Drupal\Core\Entity\Query;
diff --git a/core/lib/Drupal/Core/Entity/Query/ConditionInterface.php b/core/lib/Drupal/Core/Entity/Query/ConditionInterface.php
index e81a1d0..d48e7d5 100644
--- a/core/lib/Drupal/Core/Entity/Query/ConditionInterface.php
+++ b/core/lib/Drupal/Core/Entity/Query/ConditionInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\ConditionInterface.
+ * Contains \Drupal\Core\Entity\ConditionInterface.
  */
 
 namespace Drupal\Core\Entity\Query;
diff --git a/core/lib/Drupal/Core/Entity/Query/QueryBase.php b/core/lib/Drupal/Core/Entity/Query/QueryBase.php
index d22dbac..2e92f4b 100644
--- a/core/lib/Drupal/Core/Entity/Query/QueryBase.php
+++ b/core/lib/Drupal/Core/Entity/Query/QueryBase.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Query\QueryBase.
+ * Contains \Drupal\Core\Entity\Query\QueryBase.
  */
 
 namespace Drupal\Core\Entity\Query;
diff --git a/core/lib/Drupal/Core/Entity/Query/QueryException.php b/core/lib/Drupal/Core/Entity/Query/QueryException.php
index a1d54d6..c7be45c 100644
--- a/core/lib/Drupal/Core/Entity/Query/QueryException.php
+++ b/core/lib/Drupal/Core/Entity/Query/QueryException.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\QueryException.
+ * Contains \Drupal\Core\Entity\QueryException.
  */
 
 namespace Drupal\Core\Entity\Query;
diff --git a/core/lib/Drupal/Core/Entity/Query/QueryFactory.php b/core/lib/Drupal/Core/Entity/Query/QueryFactory.php
index 9957892..f0e7beb 100644
--- a/core/lib/Drupal/Core/Entity/Query/QueryFactory.php
+++ b/core/lib/Drupal/Core/Entity/Query/QueryFactory.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\Query\QueryFactory.
+ * Contains \Drupal\Core\Entity\Query\QueryFactory.
  */
 
 namespace Drupal\Core\Entity\Query;
diff --git a/core/lib/Drupal/Core/Entity/Query/QueryInterface.php b/core/lib/Drupal/Core/Entity/Query/QueryInterface.php
index ec9627e..366a323 100644
--- a/core/lib/Drupal/Core/Entity/Query/QueryInterface.php
+++ b/core/lib/Drupal/Core/Entity/Query/QueryInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\QueryInterface.
+ * Contains \Drupal\Core\Entity\QueryInterface.
  */
 
 namespace Drupal\Core\Entity\Query;
diff --git a/core/lib/Drupal/Core/TypedData/AccessibleInterface.php b/core/lib/Drupal/Core/TypedData/AccessibleInterface.php
index d120584..1b0dacd 100644
--- a/core/lib/Drupal/Core/TypedData/AccessibleInterface.php
+++ b/core/lib/Drupal/Core/TypedData/AccessibleInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\AccessibleInterface.
+ * Contains \Drupal\Core\TypedData\AccessibleInterface.
  */
 
 namespace Drupal\Core\TypedData;
diff --git a/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php b/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php
index d6bffc6..f735da5 100644
--- a/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php
+++ b/core/lib/Drupal/Core/TypedData/ComplexDataInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\ComplexDataInterface.
+ * Contains \Drupal\Core\TypedData\ComplexDataInterface.
  */
 
 namespace Drupal\Core\TypedData;
diff --git a/core/lib/Drupal/Core/TypedData/ContextAwareTypedData.php b/core/lib/Drupal/Core/TypedData/ContextAwareTypedData.php
index e713324..dc95294 100644
--- a/core/lib/Drupal/Core/TypedData/ContextAwareTypedData.php
+++ b/core/lib/Drupal/Core/TypedData/ContextAwareTypedData.php
@@ -12,7 +12,7 @@
  *
  * This implementation requires parent typed data objects to implement the
  * ContextAwareInterface also, such that the context can be derived from the
- * parents.
+ * parent.
  *
  * Classes deriving from this base class have to declare $value
  * or override getValue() or setValue().
@@ -74,6 +74,7 @@ public function getRoot() {
     if (isset($this->parent)) {
       return $this->parent->getRoot();
     }
+    // If no parent is set, this is the root of the data tree.
     return $this;
   }
 
@@ -82,9 +83,13 @@ public function getRoot() {
    */
   public function getPropertyPath() {
     if (isset($this->parent)) {
+      // The property path of this data object is the parent's path appended
+      // by this object's name.
       $prefix = $this->parent->getPropertyPath();
       return (strlen($prefix) ? $prefix . '.' : '') . $this->name;
     }
+    // If no parent is set, this is the root of the data tree. Thus the property
+    // path equals the name of this data object.
     elseif (isset($this->name)) {
       return $this->name;
     }
@@ -99,11 +104,4 @@ public function getPropertyPath() {
   public function getParent() {
     return $this->parent;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // @todo: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/MissingContextException.php b/core/lib/Drupal/Core/TypedData/MissingContextException.php
index d8a3fda..6ef2f8f 100644
--- a/core/lib/Drupal/Core/TypedData/MissingContextException.php
+++ b/core/lib/Drupal/Core/TypedData/MissingContextException.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\MissingContextException.
+ * Contains \Drupal\Core\TypedData\MissingContextException.
  */
 
 namespace Drupal\Core\TypedData;
diff --git a/core/lib/Drupal/Core/TypedData/Primitive.php b/core/lib/Drupal/Core/TypedData/Primitive.php
index 523a047..393e4c7 100644
--- a/core/lib/Drupal/Core/TypedData/Primitive.php
+++ b/core/lib/Drupal/Core/TypedData/Primitive.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Primitive.
+ * Contains \Drupal\Core\TypedData\Primitive.
  */
 
 namespace Drupal\Core\TypedData;
@@ -14,41 +14,57 @@
 
   /**
    * The BOOLEAN primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\Boolean
    */
   const BOOLEAN = 1;
 
   /**
    * The STRING primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\String
    */
   const STRING = 2;
 
   /**
    * The INTEGER primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\Integer
    */
   const INTEGER = 3;
 
   /**
    * The FLOAT primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\Float
    */
   const FLOAT = 4;
 
   /**
    * The DATE primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\Date
    */
   const DATE = 5;
 
   /**
    * The DURATION primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\Duration
    */
   const DURATION = 6;
 
   /**
    * The URI primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\Uri
    */
   const URI = 7;
 
   /**
    * The BINARY primitive data type.
+   *
+   * @see \Drupal\Core\TypedData\Type\Binary
    */
   const BINARY = 8;
 }
diff --git a/core/lib/Drupal/Core/TypedData/ReadOnlyException.php b/core/lib/Drupal/Core/TypedData/ReadOnlyException.php
index e5cb0d9..9e80a59 100644
--- a/core/lib/Drupal/Core/TypedData/ReadOnlyException.php
+++ b/core/lib/Drupal/Core/TypedData/ReadOnlyException.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\ReadOnlyException.
+ * Contains \Drupal\Core\TypedData\ReadOnlyException.
  */
 
 namespace Drupal\Core\TypedData;
diff --git a/core/lib/Drupal/Core/TypedData/TranslatableInterface.php b/core/lib/Drupal/Core/TypedData/TranslatableInterface.php
index 975b870..744e780 100644
--- a/core/lib/Drupal/Core/TypedData/TranslatableInterface.php
+++ b/core/lib/Drupal/Core/TypedData/TranslatableInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\TranslatableInterface.
+ * Contains \Drupal\Core\TypedData\TranslatableInterface.
  */
 
 namespace Drupal\Core\TypedData;
diff --git a/core/lib/Drupal/Core/TypedData/Type/Binary.php b/core/lib/Drupal/Core/TypedData/Type/Binary.php
index 303b71c..479ddf4 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Binary.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Binary.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Binary.
+ * Contains \Drupal\Core\TypedData\Type\Binary.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -34,9 +34,11 @@ class Binary extends TypedData {
   public $handle = NULL;
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides TypedData::getValue().
    */
   public function getValue() {
+    // If the value has been set by (absolute) stream resource URI, access the
+    // resource now.
     if (!isset($this->handle) && isset($this->uri)) {
       $this->handle = fopen($this->uri, 'rb');
     }
@@ -44,7 +46,9 @@ public function getValue() {
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
+   *
+   * Supports a PHP file resource or a (absolute) stream resource URI as value.
    */
   public function setValue($value) {
     if (!isset($value)) {
@@ -65,20 +69,14 @@ public function setValue($value) {
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides TypedData::getString().
    */
   public function getString() {
+    // Return the file content.
     $contents = '';
     while (!feof($this->getValue())) {
       $contents .= fread($this->handle, 8192);
     }
     return $contents;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/Boolean.php b/core/lib/Drupal/Core/TypedData/Type/Boolean.php
index c8797ef..62a6791 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Boolean.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Boolean.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Boolean.
+ * Contains \Drupal\Core\TypedData\Type\Boolean.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -25,16 +25,9 @@ class Boolean extends TypedData {
   protected $value;
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($value) {
     $this->value = isset($value) ? (bool) $value : $value;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/Date.php b/core/lib/Drupal/Core/TypedData/Type/Date.php
index a534280..f6c19e0 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Date.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Date.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Date.
+ * Contains \Drupal\Core\TypedData\Type\Date.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -14,10 +14,10 @@
 /**
  * The date data type.
  *
- * The plain value of a date is an instance of the DrupalDateTime class. For setting
- * the value any value supported by the __construct() of the DrupalDateTime
- * class will work, including a DateTime object, a timestamp, a string
- * date, or an array of date parts.
+ * The plain value of a date is an instance of the DrupalDateTime class. For
+ * setting the value any value supported by the __construct() of the
+ * DrupalDateTime class will work, including a DateTime object, a timestamp, a
+ * string date, or an array of date parts.
  */
 class Date extends TypedData {
 
@@ -29,7 +29,7 @@ class Date extends TypedData {
   protected $value;
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($value) {
 
@@ -45,18 +45,4 @@ public function setValue($value) {
       }
     }
   }
-
-  /**
-   * Implements TypedDataInterface::getString().
-   */
-  public function getString() {
-    return (string) $this->getValue();
-  }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/Duration.php b/core/lib/Drupal/Core/TypedData/Type/Duration.php
index d979dcf..527fbdd 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Duration.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Duration.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Duration.
+ * Contains \Drupal\Core\TypedData\Type\Duration.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -29,7 +29,7 @@ class Duration extends TypedData {
   protected $value;
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($value) {
     if ($value instanceof DateInterval || !isset($value)) {
@@ -51,18 +51,11 @@ public function setValue($value) {
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides TypedData::getString().
    */
   public function getString() {
     // Generate an ISO 8601 formatted string as supported by
     // DateInterval::__construct() and setValue().
     return (string) $this->getValue()->format('%rP%yY%mM%dDT%hH%mM%sS');
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/Float.php b/core/lib/Drupal/Core/TypedData/Type/Float.php
index 3e8369b..fe7c8b3 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Float.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Float.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Float.
+ * Contains \Drupal\Core\TypedData\Type\Float.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -25,16 +25,9 @@ class Float extends TypedData {
   protected $value;
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($value) {
     $this->value = isset($value) ? (float) $value : $value;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/Integer.php b/core/lib/Drupal/Core/TypedData/Type/Integer.php
index 4303511..487e1eb 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Integer.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Integer.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Integer.
+ * Contains \Drupal\Core\TypedData\Type\Integer.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -25,16 +25,9 @@ class Integer extends TypedData {
   protected $value;
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($value) {
     $this->value = isset($value) ? (int) $value : $value;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/Language.php b/core/lib/Drupal/Core/TypedData/Type/Language.php
index 50ae4b8..ac84070 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Language.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Language.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Language.
+ * Contains \Drupal\Core\TypedData\Type\Language.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -14,7 +14,7 @@
  * Defines the 'language' data type.
  *
  * The plain value of a language is the language object, i.e. an instance of
- * Drupal\Core\Language\Language. For setting the value the language object or
+ * \Drupal\Core\Language\Language. For setting the value the language object or
  * the language code as string may be passed.
  *
  * Optionally, this class may be used as computed property, see the supported
@@ -34,7 +34,7 @@ class Language extends ContextAwareTypedData {
   protected $langcode;
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides TypedData::getValue().
    */
   public function getValue() {
     $source = $this->getLanguageCodeSource();
@@ -54,7 +54,7 @@ protected function getLanguageCodeSource() {
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    *
    * Both the langcode and the language object may be passed as value.
    */
@@ -66,7 +66,7 @@ public function setValue($value) {
     elseif (isset($value) && !is_scalar($value)) {
       throw new InvalidArgumentException('Value is no valid langcode or language object.');
     }
-
+    // Now update the value in the source or the local langcode property.
     $source = $this->getLanguageCodeSource();
     if ($source) {
       $source->setValue($value);
@@ -77,17 +77,10 @@ public function setValue($value) {
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides TypedData::getString().
    */
   public function getString() {
     $language = $this->getValue();
     return $language ? $language->name : '';
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/String.php b/core/lib/Drupal/Core/TypedData/Type/String.php
index 9248239..f5402ad 100644
--- a/core/lib/Drupal/Core/TypedData/Type/String.php
+++ b/core/lib/Drupal/Core/TypedData/Type/String.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\String.
+ * Contains \Drupal\Core\TypedData\Type\String.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -25,16 +25,9 @@ class String extends TypedData {
   protected $value;
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($value) {
     $this->value = isset($value) ? (string) $value : $value;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/Type/Uri.php b/core/lib/Drupal/Core/TypedData/Type/Uri.php
index 52b9c3f..3dd893d 100644
--- a/core/lib/Drupal/Core/TypedData/Type/Uri.php
+++ b/core/lib/Drupal/Core/TypedData/Type/Uri.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\Type\Uri.
+ * Contains \Drupal\Core\TypedData\Type\Uri.
  */
 
 namespace Drupal\Core\TypedData\Type;
@@ -24,16 +24,9 @@ class Uri extends TypedData {
   protected $value;
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($value) {
     $this->value = isset($value) ? (string) $value : $value;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/TypedData.php b/core/lib/Drupal/Core/TypedData/TypedData.php
index 053bb70..a04b9f0 100644
--- a/core/lib/Drupal/Core/TypedData/TypedData.php
+++ b/core/lib/Drupal/Core/TypedData/TypedData.php
@@ -68,4 +68,11 @@ public function setValue($value) {
   public function getString() {
     return (string) $this->getValue();
   }
+
+  /**
+   * Implements TypedDataInterface::validate().
+   */
+  public function validate() {
+    // TODO: Implement validate() method.
+  }
 }
diff --git a/core/lib/Drupal/Core/TypedData/TypedDataFactory.php b/core/lib/Drupal/Core/TypedData/TypedDataFactory.php
index 14b05d6..39ebbce 100644
--- a/core/lib/Drupal/Core/TypedData/TypedDataFactory.php
+++ b/core/lib/Drupal/Core/TypedData/TypedDataFactory.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\TypedDataFactory.
+ * Contains \Drupal\Core\TypedData\TypedDataFactory.
  */
 
 namespace Drupal\Core\TypedData;
@@ -35,6 +35,7 @@ class TypedDataFactory extends DefaultFactory {
    *   ComplexDataInterface.
    *
    * @return \Drupal\Core\TypedData\TypedDataInterface
+   *   The instantiated typed data object.
    */
   public function createInstance($plugin_id, array $configuration, $name = NULL, $parent = NULL) {
     $type_definition = $this->discovery->getDefinition($plugin_id);
@@ -43,7 +44,8 @@ public function createInstance($plugin_id, array $configuration, $name = NULL, $
       throw new InvalidArgumentException(format_string('Invalid data type %plugin_id has been given.', array('%plugin_id' => $plugin_id)));
     }
 
-    // Allow per-data definition overrides of the used classes.
+    // Allow per-data definition overrides of the used classes, i.e. take over
+    // classes specified in the data definition.
     $key = empty($configuration['list']) ? 'class' : 'list class';
     if (isset($configuration[$key])) {
       $class = $configuration[$key];
diff --git a/core/lib/Drupal/Core/TypedData/TypedDataInterface.php b/core/lib/Drupal/Core/TypedData/TypedDataInterface.php
index 1a8ffe7..3b64de2 100644
--- a/core/lib/Drupal/Core/TypedData/TypedDataInterface.php
+++ b/core/lib/Drupal/Core/TypedData/TypedDataInterface.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\TypedData\TypedDataInterface.
+ * Contains \Drupal\Core\TypedData\TypedDataInterface.
  */
 
 namespace Drupal\Core\TypedData;
diff --git a/core/lib/Drupal/Core/TypedData/TypedDataManager.php b/core/lib/Drupal/Core/TypedData/TypedDataManager.php
index 91367ad..9f1c9c5 100644
--- a/core/lib/Drupal/Core/TypedData/TypedDataManager.php
+++ b/core/lib/Drupal/Core/TypedData/TypedDataManager.php
@@ -45,13 +45,14 @@ public function __construct() {
    *   ComplexDataInterface.
    *
    * @return \Drupal\Core\TypedData\TypedDataInterface
+   *   The instantiated typed data object.
    */
   public function createInstance($plugin_id, array $configuration, $name = NULL, $parent = NULL) {
     return $this->factory->createInstance($plugin_id, $configuration, $name, $parent);
   }
 
   /**
-   * Creates a new typed data object wrapping the passed value.
+   * Creates a new typed data object instance.
    *
    * @param array $definition
    *   The data definition array with the following array keys and values:
@@ -81,7 +82,7 @@ public function createInstance($plugin_id, array $configuration, $name = NULL, $
    *   - required: A boolean specifying whether a non-NULL value is mandatory.
    *   Further keys may be supported in certain usages, e.g. for further keys
    *   supported for entity field definitions see
-   *   Drupal\Core\Entity\StorageControllerInterface::getPropertyDefinitions().
+   *   \Drupal\Core\Entity\StorageControllerInterface::getPropertyDefinitions().
    * @param mixed $value
    *   (optional) The data value. If set, it has to match one of the supported
    *   data type format as documented for the data type classes.
@@ -94,6 +95,7 @@ public function createInstance($plugin_id, array $configuration, $name = NULL, $
    *   ComplexDataInterface.
    *
    * @return \Drupal\Core\TypedData\TypedDataInterface
+   *   The instantiated typed data object.
    *
    * @see typed_data()
    * @see \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance()
@@ -179,6 +181,8 @@ public function getPropertyInstance(ContextAwareInterface $object, $property_nam
     // Make sure we have a prototype. Then, clone the prototype and set object
     // specific values, i.e. the value and the context.
     if (!isset($this->prototypes[$key])) {
+      // Create the initial prototype. For that we need to fetch the definition
+      // of the to be created property instance from the parent.
       if ($object instanceof ComplexDataInterface) {
         $definition = $object->getPropertyDefinition($property_name);
       }
@@ -192,16 +196,17 @@ public function getPropertyInstance(ContextAwareInterface $object, $property_nam
       if (!$definition) {
         throw new InvalidArgumentException('Property ' . check_plain($property_name) . ' is unknown.');
       }
-
+      // Now create the prototype using the definition, but do not pass the
+      // given value as it will serve as prototype for any further instance.
       $this->prototypes[$key] = $this->create($definition, NULL, $property_name, $object);
     }
 
+    // Clone from the prototype, then update the parent relationship and set the
+    // data value if necessary.
     $property = clone $this->prototypes[$key];
-    // Update the parent relationship if necessary.
     if ($property instanceof ContextAwareInterface) {
       $property->setContext($property_name, $object);
     }
-    // Set the passed data value.
     if (isset($value)) {
       $property->setValue($value);
     }
diff --git a/core/modules/taxonomy/lib/Drupal/taxonomy/Type/TaxonomyTermReferenceItem.php b/core/modules/taxonomy/lib/Drupal/taxonomy/Type/TaxonomyTermReferenceItem.php
index 8eabe7d..d150615 100644
--- a/core/modules/taxonomy/lib/Drupal/taxonomy/Type/TaxonomyTermReferenceItem.php
+++ b/core/modules/taxonomy/lib/Drupal/taxonomy/Type/TaxonomyTermReferenceItem.php
@@ -17,7 +17,7 @@ class TaxonomyTermReferenceItem extends FieldItemBase {
   /**
    * Property definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see static::getPropertyDefinitions()
    *
    * @var array
    */
@@ -27,12 +27,12 @@ class TaxonomyTermReferenceItem extends FieldItemBase {
    * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['tid'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['tid'] = array(
         'type' => 'integer',
         'label' => t('Referenced taxonomy term id.'),
       );
-      self::$propertyDefinitions['entity'] = array(
+      static::$propertyDefinitions['entity'] = array(
         'type' => 'entity',
         'constraints' => array(
           'entity type' => 'taxonomy_term',
@@ -45,7 +45,7 @@ public function getPropertyDefinitions() {
         'settings' => array('id source' => 'tid'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 
   /**
diff --git a/core/modules/text/lib/Drupal/text/Type/TextItem.php b/core/modules/text/lib/Drupal/text/Type/TextItem.php
index 2077b42..d7aefc7 100644
--- a/core/modules/text/lib/Drupal/text/Type/TextItem.php
+++ b/core/modules/text/lib/Drupal/text/Type/TextItem.php
@@ -17,7 +17,7 @@ class TextItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see TextItem::getPropertyDefinitions()
    *
    * @var array
    */
@@ -28,16 +28,16 @@ class TextItem extends FieldItemBase {
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['value'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['value'] = array(
         'type' => 'string',
         'label' => t('Text value'),
       );
-      self::$propertyDefinitions['format'] = array(
+      static::$propertyDefinitions['format'] = array(
         'type' => 'string',
         'label' => t('Text format'),
       );
-      self::$propertyDefinitions['processed'] = array(
+      static::$propertyDefinitions['processed'] = array(
         'type' => 'string',
         'label' => t('Processed text'),
         'description' => t('The text value with the text format applied.'),
@@ -48,6 +48,6 @@ public function getPropertyDefinitions() {
         ),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }
diff --git a/core/modules/text/lib/Drupal/text/Type/TextSummaryItem.php b/core/modules/text/lib/Drupal/text/Type/TextSummaryItem.php
index 67624c4..13e667c 100644
--- a/core/modules/text/lib/Drupal/text/Type/TextSummaryItem.php
+++ b/core/modules/text/lib/Drupal/text/Type/TextSummaryItem.php
@@ -15,7 +15,7 @@ class TextSummaryItem extends TextItem {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see static::getPropertyDefinitions()
    *
    * @var array
    */
@@ -26,15 +26,15 @@ class TextSummaryItem extends TextItem {
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
+    if (!isset(static::$propertyDefinitions)) {
 
-      self::$propertyDefinitions = parent::getPropertyDefinitions();
+      static::$propertyDefinitions = parent::getPropertyDefinitions();
 
-      self::$propertyDefinitions['summary'] = array(
+      static::$propertyDefinitions['summary'] = array(
         'type' => 'string',
         'label' => t('Summary text value'),
       );
-      self::$propertyDefinitions['summary_processed'] = array(
+      static::$propertyDefinitions['summary_processed'] = array(
         'type' => 'string',
         'label' => t('Processed summary text'),
         'description' => t('The summary text value with the text format applied.'),
@@ -45,6 +45,6 @@ public function getPropertyDefinitions() {
         ),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }