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 5a55009..e775716 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 875b7a2..a567d7f 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;
@@ -59,7 +59,7 @@ public function __construct($entityType) {
    *   the plain value of an entity field, i.e. an array of field items.
    *   If no numerically indexed array is given, the value will be set for the
    *   first field item. For example, to set the first item of a 'name'
-   *   property one can pass:
+   *   field one can pass:
    *   @code
    *     $values = array('name' => array(0 => array('value' => 'the name')));
    *   @endcode
@@ -68,12 +68,13 @@ public function __construct($entityType) {
    *     $values = array('name' => array('value' => 'the name'));
    *   @endcode
    *   If the 'name' field is a defined as 'string_item' which supports
-   *   setting by string value, it's also possible to just pass the name string:
+   *   setting its value by a string, it's also possible to just pass the name
+   *   string:
    *   @code
    *     $values = array('name' => 'the name');
    *   @endcode
    *
-   * @return Drupal\Core\Entity\EntityInterface
+   * @return \Drupal\Core\Entity\EntityInterface
    *   A new entity object.
    */
   public function create(array $values) {
@@ -100,13 +101,12 @@ public function create(array $values) {
    * Added mapping from storage records to entities.
    */
   protected function attachLoad(&$queried_entities, $load_revision = FALSE) {
-    // Now map the record values to the according entity properties and
-    // activate compatibility mode.
+    // Map the loaded stdclass records into entity objects and according fields.
     $queried_entities = $this->mapFromStorageRecords($queried_entities, $load_revision);
 
     // Attach fields.
     if ($this->entityInfo['fieldable']) {
-      // Prepare BC compatible entities for field API.
+      // Prepare BC compatible entities before passing them to the field API.
       $bc_entities = array();
       foreach ($queried_entities as $key => $entity) {
         $bc_entities[$key] = $entity->getBCEntity();
@@ -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;
@@ -197,19 +199,17 @@ public function save(EntityInterface $entity) {
       }
       else {
         $return = drupal_write_record($this->entityInfo['base_table'], $record);
+        $entity->{$this->idKey}->value = $record->{$this->idKey};
         if ($this->revisionKey) {
-          $entity->{$this->idKey}->value = $record->{$this->idKey};
           $record->{$this->revisionKey} = $this->saveRevision($entity);
         }
         // Reset general caches, but keep caches specific to certain entities.
         $this->resetCache(array());
 
-        $entity->{$this->idKey}->value = $record->{$this->idKey};
         $entity->enforceIsNew(FALSE);
         $this->postSave($entity, FALSE);
         $this->invokeHook('insert', $entity);
       }
-      $entity->updateOriginalValues();
 
       // Ignore slave server temporarily.
       db_ignore_slave();
diff --git a/core/lib/Drupal/Core/Entity/Entity.php b/core/lib/Drupal/Core/Entity/Entity.php
index adbb047..a11bc2b 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;
@@ -426,7 +426,7 @@ public function getParent() {
    * Implements \Drupal\Core\TypedData\ContextAwareInterface::setContext().
    */
   public function setContext($name = NULL, ContextAwareInterface $parent = NULL) {
-    // As entities are always the root of the tree, we do not need to set any
-    // context.
+    // As entities are always the root of the tree of typed data, we do not need
+    // to set any parent or name.
   }
 }
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 8f5e521..d73d08b 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,31 @@ 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 these arrays would make $entity->values
+    // and $entity->fields reference themselves, 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 value 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
-    // LANGUAGE_DEFAULT by mapping the values to LANGUAGE_DEFAULT.
+    // 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]) && is_array($this->decorated->values[$name])) {
       if (isset($this->decorated->values[$name][LANGUAGE_DEFAULT]) && !isset($this->decorated->values[$name][$langcode])) {
@@ -96,6 +112,9 @@ public function __set($name, $value) {
     if (is_array($value) && $definition = $this->decorated->getPropertyDefinition($name)) {
       // If field API sets a value with a langcode in entity language, move it
       // 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.
       foreach ($value as $langcode => $data) {
         if ($langcode != LANGUAGE_DEFAULT && $langcode == $this->decorated->language()->langcode) {
           $value[LANGUAGE_DEFAULT] = $data;
@@ -104,6 +123,9 @@ public function __set($name, $value) {
       }
     }
     $this->decorated->values[$name] = $value;
+    // 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 hold the updated value.
     unset($this->decorated->fields[$name]);
   }
 
diff --git a/core/lib/Drupal/Core/Entity/EntityFormController.php b/core/lib/Drupal/Core/Entity/EntityFormController.php
index 0b3057e..6660a6e 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 53667a5..0391089 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;
@@ -11,7 +11,7 @@
  * Entity form controller variant for entity types using the new property API.
  *
  * @todo: Merge with EntityFormController and overhaul once all entity types
- * are converted to the new property API.
+ * are converted to the new entity field API.
  */
 class EntityFormControllerNG extends EntityFormController {
 
@@ -20,7 +20,7 @@ class EntityFormControllerNG extends EntityFormController {
    */
   public function form(array $form, array &$form_state, EntityInterface $entity) {
     // @todo Exploit the Field API to generate the default widgets for the
-    // entity properties.
+    // entity fields.
     $info = $entity->entityInfo();
     if (!empty($info['fieldable'])) {
       field_attach_form($entity->getBCEntity(), $form, $form_state, $this->getFormLangcode($form_state));
@@ -33,7 +33,7 @@ public function form(array $form, array &$form_state, EntityInterface $entity) {
    */
   public function validate(array $form, array &$form_state) {
     // @todo Exploit the Field API to validate the values submitted for the
-    // entity properties.
+    // entity fields.
     $entity = $this->buildEntity($form, $form_state);
     $info = $entity->entityInfo();
 
@@ -54,11 +54,12 @@ public function buildEntity(array $form, array &$form_state) {
     $entity = clone $this->getEntity($form_state);
     $entity_type = $entity->entityType();
     $info = entity_get_info($entity_type);
-    // @todo Exploit the Field API to process the submitted entity field.
+    // @todo Exploit the Field API to process the submitted entity fields.
 
-    // Copy top-level form values that are not for fields to entity properties,
-    // without changing existing entity properties that are not being edited by
-    // this form. Copying field values must be done using field_attach_submit().
+    // Copy top-level form values that are entity fields but not handled by
+    // field API without changing existing entity fields that are not being
+    // edited by this form. Values of fields handled by field API are copied
+    // by field_attach_submit() below.
     $values_excluding_fields = $info['fieldable'] ? array_diff_key($form_state['values'], field_info_instances($entity_type, $entity->bundle())) : $form_state['values'];
     $translation = $entity->getTranslation($this->getFormLangcode($form_state), FALSE);
     $definitions = $translation->getPropertyDefinitions();
@@ -68,15 +69,14 @@ public function buildEntity(array $form, array &$form_state) {
       }
     }
 
-    // Invoke all specified builders for copying form values to entity
-    // properties.
+    // Invoke all specified builders for copying form values to entity fields.
     if (isset($form['#entity_builders'])) {
       foreach ($form['#entity_builders'] as $function) {
         call_user_func_array($function, array($entity_type, $entity, &$form, &$form_state));
       }
     }
 
-    // Copy field values to the entity.
+    // Invoke field API for copying field values.
     if ($info['fieldable']) {
       field_attach_submit($entity->getBCEntity(), $form, $form_state);
     }
diff --git a/core/lib/Drupal/Core/Entity/EntityInterface.php b/core/lib/Drupal/Core/Entity/EntityInterface.php
index 94ecc3b..2f78e11 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;
@@ -15,6 +15,15 @@
 /**
  * Defines a common interface for all entity objects.
  *
+ * This interface builds upon the general interfaces provided by the typed data
+ * API, while extending them with entity-specific additions. I.e., an entity
+ * implements the ComplexDataInterface among others, thus is complex data
+ * containing fields as its data properties. The contained fields have to
+ * implement the \Drupal\Core\Entity\Field\FieldInterface, which builds upon
+ * typed data interfaces as well.
+ *
+ * @see \Drupal\Core\TypedData\TypedDataManager
+ *
  * When implementing this interface which extends Traversable, make sure to list
  * IteratorAggregate or Iterator before this interface in the implements clause.
  */
@@ -133,7 +142,7 @@ public function uri();
    * @return
    *   Either SAVED_NEW or SAVED_UPDATED, depending on the operation performed.
    *
-   * @throws Drupal\Core\Entity\EntityStorageException
+   * @throws \Drupal\Core\Entity\EntityStorageException
    *   In case of failures an exception is thrown.
    */
   public function save();
@@ -141,7 +150,7 @@ public function save();
   /**
    * Deletes an entity permanently.
    *
-   * @throws Drupal\Core\Entity\EntityStorageException
+   * @throws \Drupal\Core\Entity\EntityStorageException
    *   In case of failures an exception is thrown.
    */
   public function delete();
@@ -149,7 +158,7 @@ public function delete();
   /**
    * Creates a duplicate of the entity.
    *
-   * @return Drupal\Core\Entity\EntityInterface
+   * @return \Drupal\Core\Entity\EntityInterface
    *   A clone of the current entity with all identifiers unset, so saving
    *   it inserts a new entity into the storage system.
    */
diff --git a/core/lib/Drupal/Core/Entity/EntityListController.php b/core/lib/Drupal/Core/Entity/EntityListController.php
index 1fdb4ba..1c03fc0 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;
@@ -15,7 +15,7 @@ class EntityListController implements EntityListControllerInterface {
   /**
    * The entity storage controller class.
    *
-   * @var Drupal\Core\Entity\EntityStorageControllerInterface
+   * @var \Drupal\Core\Entity\EntityStorageControllerInterface
    */
   protected $storage;
 
@@ -40,7 +40,7 @@ class EntityListController implements EntityListControllerInterface {
    *
    * @param string $entity_type.
    *   The type of entity to be listed.
-   * @param Drupal\Core\Entity\EntityStorageControllerInterface $storage.
+   * @param \Drupal\Core\Entity\EntityStorageControllerInterface $storage.
    *   The entity storage controller class.
    */
   public function __construct($entity_type, EntityStorageControllerInterface $storage) {
@@ -101,7 +101,7 @@ public function buildHeader() {
   /**
    * Builds a row for an entity in the entity listing.
    *
-   * @param Drupal\Core\Entity\EntityInterface $entity
+   * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity for this row of the list.
    *
    * @return array
@@ -120,7 +120,7 @@ public function buildRow(EntityInterface $entity) {
   /**
    * Builds a renderable list of operation links for the entity.
    *
-   * @param Drupal\Core\Entity\EntityInterface $entity
+   * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity on which the linked operations will be performed.
    *
    * @return array
diff --git a/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php
index 85790c3..b7581d8 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;
@@ -15,7 +15,7 @@
   /**
    * Gets the entity storage controller.
    *
-   * @return Drupal\Core\Entity\EntityStorageControllerInterface
+   * @return \Drupal\Core\Entity\EntityStorageControllerInterface
    *   The storage controller used by this list controller.
    */
   public function getStorageController();
@@ -34,7 +34,7 @@ public function load();
   /**
    * Provides an array of information to build a list of operation links.
    *
-   * @param Drupal\Core\Entity\EntityInterface $entity
+   * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity the operations are for.
    *
    * @return array
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..b6d91a1 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;
@@ -16,10 +16,6 @@
 /**
  * Implements Entity Field API specific enhancements to the Entity class.
  *
- * An entity implements the ComplexDataInterface, thus is complex data
- * containing fields as its data properties. The entity fields have to implement
- * the \Drupal\Core\Entity\Field\FieldInterface.
- *
  * @todo: Once all entity types have been converted, merge improvements into the
  * Entity class and overhaul the EntityInterface.
  */
@@ -36,8 +32,8 @@ class EntityNG extends Entity {
    * The plain data values of the contained fields.
    *
    * This always holds the original, unchanged values of the entity. The values
-   * are keyed by language code, whereas LANGUAGE_NOT_SPECIFIED is used for
-   * values in default language.
+   * are keyed by language code, whereas LANGUAGE_DEFAULT is used for values in
+   * default language.
    *
    * @todo: Add methods for getting original fields and for determining
    * changes.
@@ -66,7 +62,7 @@ class EntityNG extends Entity {
   /**
    * Local cache for field definitions.
    *
-   * @see self::getPropertyDefinitions()
+   * @see static::getPropertyDefinitions()
    *
    * @var array
    */
@@ -130,7 +126,7 @@ public function uuid() {
   }
 
   /**
-   * Implements ComplexDataInterface::get().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::get().
    */
   public function get($property_name) {
     // Values in default language are always stored using the LANGUAGE_DEFAULT
@@ -147,14 +143,14 @@ public function get($property_name) {
    * @return \Drupal\Core\Entity\Field\FieldInterface
    */
   protected function getTranslatedField($property_name, $langcode) {
-    // Populate $this->properties to fasten further lookups and to keep track of
-    // property objects, possibly holding changes to properties.
+    // Populate $this->fields to fasten further look-ups and to keep track of
+    // fields objects, possibly holding changes to field values.
     if (!isset($this->fields[$property_name][$langcode])) {
       $definition = $this->getPropertyDefinition($property_name);
       if (!$definition) {
         throw new InvalidArgumentException('Field ' . check_plain($property_name) . ' is unknown.');
       }
-      // Non-translatable properties always use default language.
+      // Non-translatable fields are always stored with LANGUAGE_DEFAULT as key.
       if ($langcode != LANGUAGE_DEFAULT && empty($definition['translatable'])) {
         $this->fields[$property_name][$langcode] = $this->getTranslatedField($property_name, LANGUAGE_DEFAULT);
       }
@@ -170,14 +166,14 @@ protected function getTranslatedField($property_name, $langcode) {
   }
 
   /**
-   * Implements ComplexDataInterface::set().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::set().
    */
   public function set($property_name, $value) {
     $this->get($property_name)->setValue($value);
   }
 
   /**
-   * Implements ComplexDataInterface::getProperties().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getProperties().
    */
   public function getProperties($include_computed = FALSE) {
     $properties = array();
@@ -190,14 +186,14 @@ public function getProperties($include_computed = FALSE) {
   }
 
   /**
-   * Implements IteratorAggregate::getIterator().
+   * Implements \IteratorAggregate::getIterator().
    */
   public function getIterator() {
     return new ArrayIterator($this->getProperties());
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinition().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinition().
    */
   public function getPropertyDefinition($name) {
     if (!isset($this->fieldDefinitions)) {
@@ -212,7 +208,7 @@ public function getPropertyDefinition($name) {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
     if (!isset($this->fieldDefinitions)) {
@@ -225,7 +221,7 @@ public function getPropertyDefinitions() {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyValues().
    */
   public function getPropertyValues() {
     $values = array();
@@ -236,7 +232,7 @@ public function getPropertyValues() {
   }
 
   /**
-   * Implements ComplexDataInterface::setPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::setPropertyValues().
    */
   public function setPropertyValues($values) {
     foreach ($values as $name => $value) {
@@ -245,7 +241,7 @@ public function setPropertyValues($values) {
   }
 
   /**
-   * Implements ComplexDataInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::isEmpty().
    */
   public function isEmpty() {
     if (!$this->isNew()) {
@@ -260,7 +256,7 @@ public function isEmpty() {
   }
 
   /**
-   * Implements TranslatableInterface::language().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::language().
    */
   public function language() {
     $language = $this->get('langcode')->language;
@@ -273,7 +269,7 @@ public function language() {
   }
 
   /**
-   * Implements TranslatableInterface::getTranslation().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::getTranslation().
    *
    * @return \Drupal\Core\Entity\Field\Type\EntityTranslation
    */
@@ -316,12 +312,12 @@ public function getTranslation($langcode, $strict = TRUE) {
   }
 
   /**
-   * Implements TranslatableInterface::getTranslationLanguages().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::getTranslationLanguages().
    */
   public function getTranslationLanguages($include_default = TRUE) {
     $translations = array();
     // Build an array with the translation langcodes set as keys. Empty
-    // translations must be filtered out.
+    // translations should not be included and must be skipped.
     foreach ($this->getProperties() as $name => $property) {
       foreach ($this->fields[$name] as $langcode => $field) {
         if (!$field->isEmpty()) {
@@ -329,6 +325,8 @@ public function getTranslationLanguages($include_default = TRUE) {
         }
         if (isset($this->values[$name])) {
           foreach ($this->values[$name] as $langcode => $values) {
+            // If a value is there but the field object is empty, it has been
+            // unset, so we need to skip the field also.
             if ($values && !(isset($this->fields[$name][$langcode]) && $this->fields[$name][$langcode]->isEmpty())) {
               $translations[$langcode] = TRUE;
             }
@@ -336,12 +334,14 @@ public function getTranslationLanguages($include_default = TRUE) {
         }
       }
     }
+    // We include the default language code instead of the LANGUAGE_DEFAULT
+    // constant.
     unset($translations[LANGUAGE_DEFAULT]);
 
     if ($include_default) {
       $translations[$this->language()->langcode] = TRUE;
     }
-    // Now get languages based upon translation langcodes.
+    // Now load language objects based upon translation langcodes.
     return array_intersect_key(language_list(LANGUAGE_ALL), $translations);
   }
 
@@ -387,6 +387,8 @@ public function updateOriginalValues() {
    * For compatibility mode to work this must return a reference.
    */
   public function &__get($name) {
+    // If this is an entity field, handle it accordingly. We first check whether
+    // a field object has been already created. If not, we create one.
     if (isset($this->fields[$name][LANGUAGE_DEFAULT])) {
       return $this->fields[$name][LANGUAGE_DEFAULT];
     }
@@ -403,8 +405,8 @@ public function &__get($name) {
     if ($name == 'values' || $name == 'fields') {
       return $this->$name;
     }
-    // Else directly read/write plain values. That way, fields not yet converted
-    // to the entity field API can always be directly accessed.
+    // Else directly read/write plain values. That way, non-field entity
+    // properties can always be accessed directly.
     if (!isset($this->values[$name])) {
       $this->values[$name] = NULL;
     }
@@ -421,7 +423,8 @@ public function __set($name, $value) {
     if ($value instanceof TypedDataInterface) {
       $value = $value->getValue();
     }
-
+    // If this is an entity field, handle it accordingly. We first check whether
+    // a field object has been already created. If not, we create one.
     if (isset($this->fields[$name][LANGUAGE_DEFAULT])) {
       $this->fields[$name][LANGUAGE_DEFAULT]->setValue($value);
     }
@@ -476,7 +479,7 @@ public function createDuplicate() {
   }
 
   /**
-   * Implements a deep clone.
+   * Magic method: Implements a deep clone.
    */
   public function __clone() {
     $this->bcEntity = NULL;
diff --git a/core/lib/Drupal/Core/Entity/EntityRenderController.php b/core/lib/Drupal/Core/Entity/EntityRenderController.php
index c839031..c67c080 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;
@@ -80,7 +80,7 @@ public function buildContent(array $entities = array(), $view_mode = 'full', $la
   /**
    * Provides entity-specific defaults to the build process.
    *
-   * @param Drupal\Core\Entity\EntityInterface $entity
+   * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity for which the defaults should be provided.
    * @param string $view_mode
    *   The view mode that should be used.
@@ -105,7 +105,7 @@ protected function getBuildDefaults(EntityInterface $entity, $view_mode, $langco
    *
    * @param array $build
    *   The render array that is being created.
-   * @param Drupal\Core\Entity\EntityInterface $entity
+   * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity to be prepared.
    * @param string $view_mode
    *   The view mode that should be used to prepare the entity.
diff --git a/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php
index c24ffaa..226464e 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;
@@ -30,7 +30,7 @@ public function buildContent(array $entities = array(), $view_mode = 'full', $la
   /**
    * Returns the render array for the provided entity.
    *
-   * @param Drupal\Core\Entity\EntityInterface $entity
+   * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity to render.
    * @param string $view_mode
    *   (optional) The view mode that should be used to render the entity.
diff --git a/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php b/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php
index f5a596d..2811f1c 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;
@@ -46,7 +46,7 @@ public function load(array $ids = NULL);
    * @param int $revision_id
    *   The revision id.
    *
-   * @return Drupal\Core\Entity\EntityInterface|false
+   * @return \Drupal\Core\Entity\EntityInterface|false
    *   The specified entity revision or FALSE if not found.
    */
   public function loadRevision($revision_id);
@@ -80,7 +80,7 @@ public function loadByProperties(array $values = array());
    *   An array of values to set, keyed by property name. If the entity type has
    *   bundles the bundle key has to be specified.
    *
-   * @return Drupal\Core\Entity\EntityInterface
+   * @return \Drupal\Core\Entity\EntityInterface
    *   A new entity object.
    */
   public function create(array $values);
@@ -91,7 +91,7 @@ public function create(array $values);
    * @param array $entities
    *   An array of entity objects to delete.
    *
-   * @throws Drupal\Core\Entity\EntityStorageException
+   * @throws \Drupal\Core\Entity\EntityStorageException
    *   In case of failures, an exception is thrown.
    */
   public function delete(array $entities);
@@ -99,14 +99,14 @@ public function delete(array $entities);
   /**
    * Saves the entity permanently.
    *
-   * @param Drupal\Core\Entity\EntityInterface $entity
+   * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity to save.
    *
    * @return
    *   SAVED_NEW or SAVED_UPDATED is returned depending on the operation
    *   performed.
    *
-   * @throws Drupal\Core\Entity\EntityStorageException
+   * @throws \Drupal\Core\Entity\EntityStorageException
    *   In case of failures, an exception is thrown.
    */
   public function save(EntityInterface $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..dbd20f9 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;
@@ -15,10 +15,10 @@
 /**
  * Interface for fields, being lists of field items.
  *
- * Contained items must implement the FieldItemInterface. This
- * interface is required for every property of an entity. Some methods are
- * delegated to the first contained item, in particular get() and set() as well
- * as their magic equivalences.
+ * This interface must be implemented by every entity field, whereas contained
+ * field items must implement the FieldItemInterface.
+ * Some methods of the fields are delegated to the first contained item, in
+ * particular get() and set() as well as their magic equivalences.
  *
  * Optionally, a typed data object implementing
  * Drupal\Core\TypedData\TypedDataInterface may be passed to
@@ -64,7 +64,6 @@ public function __isset($property_name);
    */
   public function __unset($property_name);
 
-
   /**
    * Delegates to the first item.
    *
diff --git a/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php b/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php
index a1fdc6b..62d37e6 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;
@@ -32,7 +32,7 @@
    * replaced by others, so computed properties can safely store references on
    * other properties.
    *
-   * @var array<TypedDataInterface>
+   * @var TypedDataInterface[]
    */
   protected $properties = array();
 
@@ -61,7 +61,7 @@ public function __construct(array $definition, $name = NULL, ContextAwareInterfa
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides TypedData::getValue().
    */
   public function getValue() {
     $values = array();
@@ -72,7 +72,7 @@ public function getValue() {
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    *
    * @param array $values
    *   An array of property values.
@@ -98,7 +98,7 @@ public function setValue($values) {
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides TypedData::getString().
    */
   public function getString() {
     $strings = array();
@@ -109,13 +109,6 @@ public function getString() {
   }
 
   /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // @todo implement
-  }
-
-  /**
    * Implements ComplexDataInterface::get().
    */
   public function get($property_name) {
@@ -166,9 +159,8 @@ public function __unset($name) {
     }
   }
 
-
   /**
-   * Implements ComplexDataInterface::getProperties().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getProperties().
    */
   public function getProperties($include_computed = FALSE) {
     $properties = array();
@@ -181,14 +173,14 @@ public function getProperties($include_computed = FALSE) {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyValues().
    */
   public function getPropertyValues() {
     return $this->getValue();
   }
 
   /**
-   * Implements ComplexDataInterface::setPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::setPropertyValues().
    */
   public function setPropertyValues($values) {
     foreach ($values as $name => $value) {
@@ -197,14 +189,14 @@ public function setPropertyValues($values) {
   }
 
   /**
-   * Implements IteratorAggregate::getIterator().
+   * Implements \IteratorAggregate::getIterator().
    */
   public function getIterator() {
     return new ArrayIterator($this->getProperties());
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinition().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinition().
    */
   public function getPropertyDefinition($name) {
     $definitions = $this->getPropertyDefinitions();
@@ -217,7 +209,7 @@ public function getPropertyDefinition($name) {
   }
 
   /**
-   * Implements ComplexDataInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::isEmpty().
    */
   public function isEmpty() {
     foreach ($this->getProperties() as $property) {
@@ -229,7 +221,7 @@ public function isEmpty() {
   }
 
   /**
-   * Implements a deep clone.
+   * Magic method: Implements a deep clone.
    */
   public function __clone() {
     foreach ($this->properties as $name => $property) {
diff --git a/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php b/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php
index 2b94e7a..53e4904 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;
@@ -12,8 +12,10 @@
 use Drupal\Core\TypedData\TypedDataInterface;
 
 /**
- * Interface for entity field items, which are complex data objects
- * containing the values.
+ * Interface for entity field items.
+ *
+ * Entity field items are typed data objects containing the field values, i.e.
+ * implementing the ComplexDataInterface.
  *
  * When implementing this interface which extends Traversable, make sure to list
  * IteratorAggregate or Iterator before this interface in the implements clause.
@@ -24,7 +26,7 @@
 interface FieldItemInterface extends ComplexDataInterface, ContextAwareInterface, TypedDataInterface {
 
   /**
-   * Magic getter: Get the property value.
+   * Magic getter: Get a property value.
    *
    * @param $property_name
    *   The name of the property to get; e.g., 'title' or 'name'.
@@ -38,7 +40,7 @@
   public function __get($property_name);
 
   /**
-   * Magic setter: Set the property value.
+   * Magic setter: Set a property value.
    *
    * @param $property_name
    *   The name of the property to set; e.g., 'title' or 'name'.
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..965b720 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];
   }
 
   /**
@@ -61,7 +61,7 @@ public function getPropertyDefinitions() {
    */
   public function setValue($values) {
     // Treat the values as property value of the entity field, if no array
-    // is given.
+    // is given. That way we support setting the field by entity ID or object.
     if (!is_array($values)) {
       $values = array('entity' => $values);
     }
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php b/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php
index b4fe089..cf45b88 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;
@@ -15,17 +15,20 @@
 use InvalidArgumentException;
 
 /**
- * Makes translated entity properties available via the Field API.
+ * Allows accessing and updating translated entity fields.
+ *
+ * Via this object translated entity fields may be read and updated in the same
+ * way as untranslatable entity fields on the entity object.
  */
 class EntityTranslation extends ContextAwareTypedData implements IteratorAggregate, AccessibleInterface, ComplexDataInterface {
 
   /**
-   * The array of translated properties, each being an instance of
-   * FieldInterface.
+   * The array of translated fields, each being an instance of
+   * \Drupal\Core\Entity\FieldInterface.
    *
    * @var array
    */
-  protected $properties = array();
+  protected $fields = array();
 
   /**
    * Whether the entity translation acts in strict mode.
@@ -57,22 +60,23 @@ public function setStrictMode($strict = TRUE) {
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides TypedData::getValue().
    */
   public function getValue() {
-    // The value of the translation is the array of translated property objects.
-    return $this->properties;
+    // The plain value of the translation is the array of translated field
+    // objects.
+    return $this->fields;
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    */
   public function setValue($values) {
-    $this->properties = $values;
+    $this->fields = $values;
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides TypedData::getString().
    */
   public function getString() {
     $strings = array();
@@ -83,14 +87,14 @@ public function getString() {
   }
 
   /**
-   * Implements TypedDataInterface::get().
+   * Implements ComplexDataInterface::get().
    */
   public function get($property_name) {
     $definitions = $this->getPropertyDefinitions();
     if (!isset($definitions[$property_name])) {
       throw new InvalidArgumentException(format_string('Field @name is unknown or not translatable.', array('@name' => $property_name)));
     }
-    return $this->properties[$property_name];
+    return $this->fields[$property_name];
   }
 
   /**
@@ -114,14 +118,14 @@ public function getProperties($include_computed = FALSE) {
   }
 
   /**
-   * Magic getter: Gets the translated property.
+   * Magic getter: Gets a translated field.
    */
   public function __get($name) {
     return $this->get($name);
   }
 
   /**
-   * Magic getter: Sets the translated property.
+   * Magic getter: Sets a translated field.
    */
   public function __set($name, $value) {
     $this->get($name)->setValue($value);
@@ -193,16 +197,11 @@ public function isEmpty() {
    */
   public function access($operation = 'view', \Drupal\user\Plugin\Core\Entity\User $account = NULL) {
     $method = $operation . 'Access';
+    // Determine the language code of this translation by cutting of the
+    // leading "@" from the property name to get the langcode.
     // @todo Add a way to set and get the langcode so that's more obvious what
     // we're doing here.
-    $langocde = substr($this->getName(), 1);
-    return entity_access_controller($this->parent->entityType())->$method($this->parent, $langocde, $account);
-  }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate($value = NULL) {
-    // @todo implement
+    $langcode = substr($this->getName(), 1);
+    return entity_access_controller($this->parent->entityType())->$method($this->parent, $langcode, $account);
   }
 }
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php b/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php
index ffc9fd1..9bf95fa 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;
@@ -61,7 +61,7 @@ public function __construct(array $definition, $name = NULL, ContextAwareInterfa
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides TypedData::getValue().
    */
   public function getValue() {
     $source = $this->getIdSource();
@@ -79,7 +79,7 @@ protected function getIdSource() {
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    *
    * Both the entity ID and the entity object may be passed as value.
    */
@@ -92,7 +92,7 @@ public function setValue($value) {
     elseif (isset($value) && !(is_scalar($value) && !empty($this->definition['constraints']['entity type']))) {
       throw new InvalidArgumentException('Value is no valid entity.');
     }
-
+    // Now update the value in the source or the local id property.
     $source = $this->getIdSource();
     if ($source) {
       $source->setValue($value);
@@ -103,7 +103,7 @@ public function setValue($value) {
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides TypedData::getString().
    */
   public function getString() {
     if ($entity = $this->getValue()) {
@@ -113,13 +113,6 @@ public function getString() {
   }
 
   /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate($value = NULL) {
-    // TODO: Implement validate() method.
-  }
-
-  /**
    * Implements IteratorAggregate::getIterator().
    */
   public function getIterator() {
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/Field.php b/core/lib/Drupal/Core/Entity/Field/Type/Field.php
index 03d17e4..282d72c 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;
@@ -17,7 +17,7 @@
 use InvalidArgumentException;
 
 /**
- * An entity field, i.e. a list of field items.
+ * An entity field, i.e. a list of field item objects.
  *
  * An entity field is a list of field items, which contain only primitive
  * properties or entity references. Note that even single-valued entity
@@ -42,15 +42,15 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
    */
   public function __construct(array $definition, $name = NULL, ContextAwareInterface $parent = NULL) {
     parent::__construct($definition, $name, $parent);
-    // Always initialize one empty item as usually that will be needed. That
-    // way prototypes created by
+    // Always initialize one empty item as most times a value for at least one
+    // item will be present. That way prototypes created by
     // \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance() will
-    // already have one field item ready for use after cloning.
+    // already have this field item ready for use after cloning.
     $this->list[0] = $this->createItem(0);
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides TypedData::getValue().
    */
   public function getValue() {
     if (isset($this->list)) {
@@ -68,10 +68,10 @@ public function getValue() {
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    *
    * @param array $values
-   *   An array of values of the field items.
+   *   An array of values of the field items, or NULL to unset the field.
    */
   public function setValue($values) {
     if (!isset($values) || $values === array()) {
@@ -104,14 +104,12 @@ public function setValue($values) {
   }
 
   /**
-   * Returns a string representation of the field.
-   *
-   * @return string
+   * Overrides TypedData::getString().
    */
   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));
@@ -119,13 +117,6 @@ public function getString() {
   }
 
   /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // @todo implement
-  }
-
-  /**
    * Implements ArrayAccess::offsetExists().
    */
   public function offsetExists($offset) {
@@ -166,14 +157,14 @@ protected function createItem($offset = 0, $value = NULL) {
   }
 
   /**
-   * Implements ListInterface::getItemDefinition().
+   * Implements \Drupal\Core\TypedData\ListInterface::getItemDefinition().
    */
   public function getItemDefinition() {
     return array('list' => FALSE) + $this->definition;
   }
 
   /**
-   * Implements ArrayAccess::offsetSet().
+   * Implements \ArrayAccess::offsetSet().
    */
   public function offsetSet($offset, $value) {
     if (!isset($offset)) {
@@ -193,7 +184,7 @@ public function offsetSet($offset, $value) {
   }
 
   /**
-   * Implements IteratorAggregate::getIterator().
+   * Implements \IteratorAggregate::getIterator().
    */
   public function getIterator() {
     if (isset($this->list)) {
@@ -203,63 +194,63 @@ public function getIterator() {
   }
 
   /**
-   * Implements Countable::count().
+   * Implements \Countable::count().
    */
   public function count() {
     return isset($this->list) ? count($this->list) : 0;
   }
 
   /**
-   * Delegate.
+   * Delegates to the first item.
    */
   public function getPropertyDefinition($name) {
     return $this->offsetGet(0)->getPropertyDefinition($name);
   }
 
   /**
-   * Delegate.
+   * Delegates to the first item.
    */
   public function getPropertyDefinitions() {
     return $this->offsetGet(0)->getPropertyDefinitions();
   }
 
   /**
-   * Delegate.
+   * Delegates to the first item.
    */
   public function __get($property_name) {
     return $this->offsetGet(0)->get($property_name)->getValue();
   }
 
   /**
-   * Delegate.
+   * Delegates to the first item.
    */
   public function get($property_name) {
     return $this->offsetGet(0)->get($property_name);
   }
 
   /**
-   * Delegate.
+   * Delegates to the first item.
    */
   public function __set($property_name, $value) {
     $this->offsetGet(0)->__set($property_name, $value);
   }
 
   /**
-   * Delegate.
+   * Delegates to the first item.
    */
   public function __isset($property_name) {
     return $this->offsetGet(0)->__isset($property_name);
   }
 
   /**
-   * Delegate.
+   * Delegates to the first item.
    */
   public function __unset($property_name) {
     return $this->offsetGet(0)->__unset($property_name);
   }
 
   /**
-   * Implements ListInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ListInterface::isEmpty().
    */
   public function isEmpty() {
     if (isset($this->list)) {
@@ -273,13 +264,13 @@ public function isEmpty() {
   }
 
   /**
-   * Implements a deep clone.
+   * Magic method: Implements a deep clone.
    */
   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);
         }
       }
@@ -287,7 +278,7 @@ public function __clone() {
   }
 
   /**
-   * Implements AccessibleInterface::access().
+   * Implements \Drupal\Core\TypedData\AccessibleInterface::access().
    */
   public function access($operation = 'view', User $account = NULL) {
     // TODO: Implement access() method. Use item access.
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..2492a1d 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;
   }
 
   /**
@@ -51,7 +51,8 @@ public function getPropertyDefinitions() {
    */
   public function setValue($values) {
     // Treat the values as property value of the object property, if no array
-    // is given.
+    // is given. That way we support setting the field by language code or
+    // object.
     if (!is_array($values)) {
       $values = array('language' => $values);
     }
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;
   }
 }