commit 784bb8ff84dee9a25b6158344e26851b4525bcd2
Author: fago <nuppla@zites.net>
Date:   Fri Jan 4 13:46:47 2013 +0100

    workd through entity system

diff --git a/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php b/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php
index f7a031d..021cd0a 100644
--- a/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php
+++ b/core/lib/Drupal/Core/Entity/DatabaseStorageControllerNG.php
@@ -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();
@@ -199,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 177e943..a11bc2b 100644
--- a/core/lib/Drupal/Core/Entity/Entity.php
+++ b/core/lib/Drupal/Core/Entity/Entity.php
@@ -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/EntityBCDecorator.php b/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
index 75ba243..6a9a77b 100644
--- a/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
+++ b/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
@@ -111,6 +111,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;
@@ -119,6 +122,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/EntityFormControllerNG.php b/core/lib/Drupal/Core/Entity/EntityFormControllerNG.php
index ac30d5c..b085df9 100644
--- a/core/lib/Drupal/Core/Entity/EntityFormControllerNG.php
+++ b/core/lib/Drupal/Core/Entity/EntityFormControllerNG.php
@@ -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->entityType(), $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_type, $entity->getBCEntity(), $form, $form_state);
     }
diff --git a/core/lib/Drupal/Core/Entity/EntityInterface.php b/core/lib/Drupal/Core/Entity/EntityInterface.php
index a435ddc..2f78e11 100644
--- a/core/lib/Drupal/Core/Entity/EntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityInterface.php
@@ -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 d0d88f2..1c03fc0 100644
--- a/core/lib/Drupal/Core/Entity/EntityListController.php
+++ b/core/lib/Drupal/Core/Entity/EntityListController.php
@@ -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 ec8bc7c..b7581d8 100644
--- a/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityListControllerInterface.php
@@ -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/EntityNG.php b/core/lib/Drupal/Core/Entity/EntityNG.php
index 7216a71..b6d91a1 100644
--- a/core/lib/Drupal/Core/Entity/EntityNG.php
+++ b/core/lib/Drupal/Core/Entity/EntityNG.php
@@ -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.
@@ -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 273127e..8a312cf 100644
--- a/core/lib/Drupal/Core/Entity/EntityRenderController.php
+++ b/core/lib/Drupal/Core/Entity/EntityRenderController.php
@@ -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 d74a2a7..226464e 100644
--- a/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityRenderControllerInterface.php
@@ -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 ee0302d..2811f1c 100644
--- a/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityStorageControllerInterface.php
@@ -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/Field/FieldInterface.php b/core/lib/Drupal/Core/Entity/Field/FieldInterface.php
index 6aae6f7..dbd20f9 100644
--- a/core/lib/Drupal/Core/Entity/Field/FieldInterface.php
+++ b/core/lib/Drupal/Core/Entity/Field/FieldInterface.php
@@ -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 461464e..62d37e6 100644
--- a/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php
+++ b/core/lib/Drupal/Core/Entity/Field/FieldItemBase.php
@@ -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 7749c50..53e4904 100644
--- a/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php
+++ b/core/lib/Drupal/Core/Entity/Field/FieldItemInterface.php
@@ -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/EntityReferenceItem.php b/core/lib/Drupal/Core/Entity/Field/Type/EntityReferenceItem.php
index 270734c..965b720 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/EntityReferenceItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/EntityReferenceItem.php
@@ -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 d4052c5..6b53c88 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/EntityTranslation.php
@@ -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 untranslated 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);
@@ -200,11 +204,4 @@ public function access($operation = 'view', \Drupal\user\Plugin\Core\Entity\User
     $langcode = substr($this->getName(), 1);
     return entity_access_controller($this->parent->entityType())->$method($this->parent, $langcode, $account);
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate($value = NULL) {
-    // @todo implement
-  }
 }
diff --git a/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php b/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php
index 6df8b2e..9bf95fa 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/EntityWrapper.php
@@ -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 3766b92..282d72c 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/Field.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/Field.php
@@ -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
@@ -50,7 +50,7 @@ public function __construct(array $definition, $name = NULL, ContextAwareInterfa
   }
 
   /**
-   * 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,9 +104,7 @@ public function setValue($values) {
   }
 
   /**
-   * Returns a string representation of the field.
-   *
-   * @return string
+   * Overrides TypedData::getString().
    */
   public function getString() {
     $strings = array();
@@ -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,7 +264,7 @@ public function isEmpty() {
   }
 
   /**
-   * Implements a deep clone.
+   * Magic method: Implements a deep clone.
    */
   public function __clone() {
     if (isset($this->list)) {
@@ -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/LanguageItem.php b/core/lib/Drupal/Core/Entity/Field/Type/LanguageItem.php
index 2014556..2492a1d 100644
--- a/core/lib/Drupal/Core/Entity/Field/Type/LanguageItem.php
+++ b/core/lib/Drupal/Core/Entity/Field/Type/LanguageItem.php
@@ -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);
     }