Issue #1877632 by fago, jhodgdon: Improve comments and clean-up code for EntityNG and the TypedData API.

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;

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;
@@ -155,7 +155,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::resetCache().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::resetCache().
    */
   public function resetCache(array $ids = NULL) {
     if (isset($ids)) {
@@ -169,7 +169,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::load().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::load().
    */
   public function load(array $ids = NULL) {
     $entities = array();
@@ -236,7 +236,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::loadRevision().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::loadRevision().
    */
   public function loadRevision($revision_id) {
     // Build and execute the query.
@@ -260,7 +260,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::deleteRevision().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::deleteRevision().
    */
   public function deleteRevision($revision_id) {
     if ($revision = $this->loadRevision($revision_id)) {
@@ -277,7 +277,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::loadByProperties().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::loadByProperties().
    */
   public function loadByProperties(array $values = array()) {
     // Build a query to fetch the entity IDs.
@@ -438,7 +438,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::create().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::create().
    */
   public function create(array $values) {
     $class = $this->entityInfo['class'];
@@ -459,7 +459,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::delete().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::delete().
    */
   public function delete(array $entities) {
     if (!$entities) {
@@ -503,7 +503,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::save().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::save().
    */
   public function save(EntityInterface $entity) {
     $transaction = db_transaction();
@@ -666,17 +666,17 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::getFieldDefinitions().
+   * 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(),
       );
 
@@ -700,12 +700,12 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
 
     $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];
@@ -721,7 +721,7 @@ class DatabaseStorageController implements EntityStorageControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityStorageControllerInterface::getQueryServiceName().
+   * Implements \Drupal\Core\Entity\EntityStorageControllerInterface::getQueryServiceName().
    */
   public function getQueryServiceName() {
     return 'entity.query.field_sql_storage';

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;
@@ -20,6 +20,10 @@ use Drupal\Component\Uuid\Uuid;
  *
  * @todo: Once all entity types have been converted, merge improvements into the
  * DatabaseStorageController class.
+ *
+ * See the EntityNG documentation for an explanation of "NG".
+ *
+ * @see \Drupal\Core\EntityNG
  */
 class DatabaseStorageControllerNG extends DatabaseStorageController {
 
@@ -72,7 +76,7 @@ class DatabaseStorageControllerNG extends DatabaseStorageController {
    *   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
@@ -81,12 +85,13 @@ class DatabaseStorageControllerNG extends DatabaseStorageController {
    *     $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) {
@@ -146,13 +151,12 @@ class DatabaseStorageControllerNG extends DatabaseStorageController {
    * 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();
@@ -196,7 +200,9 @@ class DatabaseStorageControllerNG extends DatabaseStorageController {
     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;
@@ -296,8 +302,8 @@ class DatabaseStorageControllerNG extends DatabaseStorageController {
       }
       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);
         }
         $entity->{$this->idKey}->value = $record->{$this->idKey};
@@ -312,7 +318,6 @@ class DatabaseStorageControllerNG extends DatabaseStorageController {
         $this->postSave($entity, FALSE);
         $this->invokeHook('insert', $entity);
       }
-      $entity->updateOriginalValues();
 
       // Ignore slave server temporarily.
       db_ignore_slave();

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;
@@ -75,28 +75,28 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements EntityInterface::id().
+   * Implements \Drupal\Core\Entity\EntityInterface::id().
    */
   public function id() {
     return isset($this->id) ? $this->id : NULL;
   }
 
   /**
-   * Implements EntityInterface::uuid().
+   * Implements \Drupal\Core\Entity\EntityInterface::uuid().
    */
   public function uuid() {
     return isset($this->uuid) ? $this->uuid : NULL;
   }
 
   /**
-   * Implements EntityInterface::isNew().
+   * Implements \Drupal\Core\Entity\EntityInterface::isNew().
    */
   public function isNew() {
     return !empty($this->enforceIsNew) || !$this->id();
   }
 
   /**
-   * Implements EntityInterface::isNewRevision().
+   * Implements \Drupal\Core\Entity\EntityInterface::isNewRevision().
    */
   public function isNewRevision() {
     $info = $this->entityInfo();
@@ -104,35 +104,35 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements EntityInterface::enforceIsNew().
+   * Implements \Drupal\Core\Entity\EntityInterface::enforceIsNew().
    */
   public function enforceIsNew($value = TRUE) {
     $this->enforceIsNew = $value;
   }
 
   /**
-   * Implements EntityInterface::setNewRevision().
+   * Implements \Drupal\Core\Entity\EntityInterface::setNewRevision().
    */
   public function setNewRevision($value = TRUE) {
     $this->newRevision = $value;
   }
 
   /**
-   * Implements EntityInterface::entityType().
+   * Implements \Drupal\Core\Entity\EntityInterface::entityType().
    */
   public function entityType() {
     return $this->entityType;
   }
 
   /**
-   * Implements EntityInterface::bundle().
+   * Implements \Drupal\Core\Entity\EntityInterface::bundle().
    */
   public function bundle() {
     return $this->entityType;
   }
 
   /**
-   * Implements EntityInterface::label().
+   * Implements \Drupal\Core\Entity\EntityInterface::label().
    */
   public function label($langcode = NULL) {
     $label = NULL;
@@ -147,7 +147,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements EntityInterface::uri().
+   * Implements \Drupal\Core\Entity\EntityInterface::uri().
    */
   public function uri() {
     $bundle = $this->bundle();
@@ -177,7 +177,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements EntityInterface::get().
+   * Implements \Drupal\Core\Entity\EntityInterface::get().
    */
   public function get($property_name, $langcode = NULL) {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -186,7 +186,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::set().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::set().
    */
   public function set($property_name, $value) {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -195,7 +195,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::getProperties().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getProperties().
    */
   public function getProperties($include_computed = FALSE) {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -203,7 +203,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyValues().
    */
   public function getPropertyValues() {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -211,7 +211,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::setPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::setPropertyValues().
    */
   public function setPropertyValues($values) {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -219,7 +219,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinition().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinition().
    */
   public function getPropertyDefinition($name) {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -227,7 +227,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -235,7 +235,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::isEmpty().
    */
   public function isEmpty() {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -243,7 +243,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements ComplexDataInterface::getIterator().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getIterator().
    */
   public function getIterator() {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -251,7 +251,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements AccessibleInterface::access().
+   * Implements \Drupal\Core\TypedData\AccessibleInterface::access().
    */
   public function access($operation = 'view', \Drupal\user\Plugin\Core\Entity\User $account = NULL) {
     $method = $operation . 'Access';
@@ -261,7 +261,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements TranslatableInterface::language().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::language().
    */
   public function language() {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -275,7 +275,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements TranslatableInterface::getTranslation().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::getTranslation().
    */
   public function getTranslation($langcode, $strict = TRUE) {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -287,14 +287,14 @@ class Entity implements IteratorAggregate, EntityInterface {
    *
    * @todo: Remove once all entity types implement the entity field API.
    *   This is deprecated by
-   *   Drupal\Core\TypedData\TranslatableInterface::getTranslationLanguages().
+   *   \Drupal\Core\TypedData\TranslatableInterface::getTranslationLanguages().
    */
   public function translations() {
     return $this->getTranslationLanguages(FALSE);
   }
 
   /**
-   * Implements TranslatableInterface::getTranslationLanguages().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::getTranslationLanguages().
    */
   public function getTranslationLanguages($include_default = TRUE) {
     // @todo: Replace by EntityNG implementation once all entity types have been
@@ -325,14 +325,14 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements EntityInterface::save().
+   * Implements \Drupal\Core\Entity\EntityInterface::save().
    */
   public function save() {
     return drupal_container()->get('plugin.manager.entity')->getStorageController($this->entityType)->save($this);
   }
 
   /**
-   * Implements EntityInterface::delete().
+   * Implements \Drupal\Core\Entity\EntityInterface::delete().
    */
   public function delete() {
     if (!$this->isNew()) {
@@ -341,7 +341,7 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements EntityInterface::createDuplicate().
+   * Implements \Drupal\Core\Entity\EntityInterface::createDuplicate().
    */
   public function createDuplicate() {
     $duplicate = clone $this;
@@ -357,21 +357,21 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements EntityInterface::entityInfo().
+   * Implements \Drupal\Core\Entity\EntityInterface::entityInfo().
    */
   public function entityInfo() {
     return entity_get_info($this->entityType);
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityInterface::getRevisionId().
+   * Implements \Drupal\Core\Entity\EntityInterface::getRevisionId().
    */
   public function getRevisionId() {
     return NULL;
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityInterface::isDefaultRevision().
+   * Implements \Drupal\Core\Entity\EntityInterface::isDefaultRevision().
    */
   public function isDefaultRevision($new_value = NULL) {
     $return = $this->isDefaultRevision;
@@ -382,21 +382,21 @@ class Entity implements IteratorAggregate, EntityInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityInterface::getExportProperties().
+   * Implements \Drupal\Core\Entity\EntityInterface::getExportProperties().
    */
   public function getExportProperties() {
     return array();
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityInterface::getBCEntity().
+   * Implements \Drupal\Core\Entity\EntityInterface::getBCEntity().
    */
   public function getBCEntity() {
     return $this;
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityInterface::getOriginalEntity().
+   * Implements \Drupal\Core\Entity\EntityInterface::getOriginalEntity().
    */
   public function getOriginalEntity() {
     return $this;
@@ -434,7 +434,7 @@ class Entity implements IteratorAggregate, EntityInterface {
    * 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.
   }
 }

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;
@@ -18,28 +18,28 @@ use Drupal\user\Plugin\Core\Entity\User;
 class EntityAccessController implements EntityAccessControllerInterface {
 
   /**
-   * Implements EntityAccessControllerInterface::viewAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::viewAccess().
    */
   public function viewAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     return FALSE;
   }
 
   /**
-   * Implements EntityAccessControllerInterface::createAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::createAccess().
    */
   public function createAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     return FALSE;
   }
 
   /**
-   * Implements EntityAccessControllerInterface::updateAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::updateAccess().
    */
   public function updateAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     return FALSE;
   }
 
   /**
-   * Implements EntityAccessControllerInterface::deleteAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::deleteAccess().
    */
   public function deleteAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     return FALSE;

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;

core/lib/Drupal/Core/Entity/EntityBCDecorator.php

@@ -12,17 +12,29 @@ use Drupal\Core\Entity\EntityInterface;
 use Drupal\Core\TypedData\ContextAwareInterface;
 
 /**
- * Implements a decorator providing backwards compatible entity field access.
+ * Provides backwards compatible (BC) access to entity fields.
  *
- * Allows using entities converted to the new Entity Field API with the Drupal 7
- * way of accessing fields or properties.
+ * Allows using entities converted to the new Entity Field API with the previous
+ * way of accessing fields or properties. For example, via the backwards
+ * compatible (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
+ * Without the BC decorator the language always default to the entity language,
+ * whereas a specific translation can be access via the getTranslation() method.
  *
- * 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).
+ * The BC decorator should be only used during conversion to the new entity
+ * field API, such that existing code can be converted iteratively. Any new code
+ * should directly use the new entity field API and avoid using the
+ * EntityBCDecorator, if possible.
+ *
+ * @todo: Remove once everything is converted to use the new entity field API.
  */
 class EntityBCDecorator implements IteratorAggregate, EntityInterface {
 
@@ -63,17 +75,31 @@ class EntityBCDecorator implements IteratorAggregate, EntityInterface {
    * 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 +122,9 @@ class EntityBCDecorator implements IteratorAggregate, EntityInterface {
     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 +133,9 @@ class EntityBCDecorator implements IteratorAggregate, EntityInterface {
       }
     }
     $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]);
   }
 

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;
@@ -33,7 +33,7 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::build().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::build().
    */
   public function build(array $form, array &$form_state, EntityInterface $entity) {
 
@@ -151,7 +151,7 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::validate().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::validate().
    */
   public function validate(array $form, array &$form_state) {
     // @todo Exploit the Field API to validate the values submitted for the
@@ -170,7 +170,7 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::submit().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::submit().
    *
    * This is the default entity object builder function. It is called before any
    * other submit handler to build the new entity object to be passed to the
@@ -219,7 +219,7 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::getFormLangcode().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::getFormLangcode().
    */
   public function getFormLangcode(array $form_state) {
     $entity = $this->getEntity($form_state);
@@ -245,7 +245,7 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements EntityFormControllerInterface::isDefaultFormLangcode().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::isDefaultFormLangcode().
    */
   public function isDefaultFormLangcode(array $form_state) {
     return $this->getFormLangcode($form_state) == $this->getEntity($form_state)->language()->langcode;
@@ -301,7 +301,7 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::buildEntity().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::buildEntity().
    */
   public function buildEntity(array $form, array &$form_state) {
     $entity = clone $this->getEntity($form_state);
@@ -312,14 +312,14 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::getEntity().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::getEntity().
    */
   public function getEntity(array $form_state) {
     return isset($form_state['entity']) ? $form_state['entity'] : NULL;
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::setEntity().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::setEntity().
    */
   public function setEntity(EntityInterface $entity, array &$form_state) {
     $form_state['entity'] = $entity;
@@ -333,7 +333,7 @@ class EntityFormController implements EntityFormControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityFormControllerInterface::getOperation().
+   * Implements \Drupal\Core\Entity\EntityFormControllerInterface::getOperation().
    */
   public function getOperation() {
     return $this->operation;

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;

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,11 @@ namespace Drupal\Core\Entity;
  * 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.
+ *
+ * See the EntityNG documentation for an explanation of "NG".
+ *
+ * @see \Drupal\Core\EntityNG
  */
 class EntityFormControllerNG extends EntityFormController {
 
@@ -20,7 +24,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 +37,7 @@ class EntityFormControllerNG extends EntityFormController {
    */
   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();
 
@@ -64,11 +68,12 @@ class EntityFormControllerNG extends EntityFormController {
     $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();
@@ -78,15 +83,14 @@ class EntityFormControllerNG extends EntityFormController {
       }
     }
 
-    // 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);
     }

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,8 +15,18 @@ use Drupal\Core\TypedData\TranslatableInterface;
 /**
  * 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.
+ *
  * When implementing this interface which extends Traversable, make sure to list
  * IteratorAggregate or Iterator before this interface in the implements clause.
+ *
+ * @see \Drupal\Core\TypedData\TypedDataManager
+ * @see \Drupal\Core\Field\FieldInterface
  */
 interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, AccessibleInterface, TranslatableInterface {
 
@@ -49,7 +59,7 @@ interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, A
    * @return
    *   TRUE if the entity is new, or FALSE if the entity has already been saved.
    *
-   * @see Drupal\Core\Entity\EntityInterface::enforceIsNew()
+   * @see \Drupal\Core\Entity\EntityInterface::enforceIsNew()
    */
   public function isNew();
 
@@ -59,7 +69,7 @@ interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, A
    * @return bool
    *   TRUE if a new revision should be created.
    *
-   * @see Drupal\Core\Entity\EntityInterface::setNewRevision()
+   * @see \Drupal\Core\Entity\EntityInterface::setNewRevision()
    */
   public function isNewRevision();
 
@@ -69,7 +79,7 @@ interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, A
    * @param bool $value
    *   (optional) Whether a new revision should be saved.
    *
-   * @see Drupal\Core\Entity\EntityInterface::isNewRevision()
+   * @see \Drupal\Core\Entity\EntityInterface::isNewRevision()
    */
   public function setNewRevision($value = TRUE);
 
@@ -83,7 +93,7 @@ interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, A
    *   (optional) Whether the entity should be forced to be new. Defaults to
    *   TRUE.
    *
-   * @see Drupal\Core\Entity\EntityInterface::isNew()
+   * @see \Drupal\Core\Entity\EntityInterface::isNew()
    */
   public function enforceIsNew($value = TRUE);
 
@@ -133,7 +143,7 @@ interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, A
    * @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 +151,7 @@ interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, A
   /**
    * 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 +159,7 @@ interface EntityInterface extends ContextAwareInterface, ComplexDataInterface, A
   /**
    * 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.
    */

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) {
@@ -50,21 +50,21 @@ class EntityListController implements EntityListControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityListControllerInterface::getStorageController().
+   * Implements \Drupal\Core\Entity\EntityListControllerInterface::getStorageController().
    */
   public function getStorageController() {
     return $this->storage;
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityListControllerInterface::load().
+   * Implements \Drupal\Core\Entity\EntityListControllerInterface::load().
    */
   public function load() {
     return $this->storage->load();
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityListControllerInterface::getOperations().
+   * Implements \Drupal\Core\Entity\EntityListControllerInterface::getOperations().
    */
   public function getOperations(EntityInterface $entity) {
     $uri = $entity->uri();
@@ -101,7 +101,7 @@ class EntityListController implements EntityListControllerInterface {
   /**
    * 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 @@ class EntityListController implements EntityListControllerInterface {
   /**
    * 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
@@ -140,7 +140,7 @@ class EntityListController implements EntityListControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityListControllerInterface::render().
+   * Implements \Drupal\Core\Entity\EntityListControllerInterface::render().
    *
    * Builds the entity list as renderable array for theme_table().
    *

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 @@ interface EntityListControllerInterface {
   /**
    * 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 @@ interface EntityListControllerInterface {
   /**
    * 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

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;

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,9 +16,10 @@ use InvalidArgumentException;
 /**
  * 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.
+ * Entity(..)NG classes are variants of the Entity(...) classes that implement
+ * the next generation (NG) entity field API. They exist during conversion to
+ * the new API only and changes will be merged into the respective original
+ * classes once the conversion is complete.
  *
  * @todo: Once all entity types have been converted, merge improvements into the
  * Entity class and overhaul the EntityInterface.
@@ -36,8 +37,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 +67,7 @@ class EntityNG extends Entity {
   /**
    * Local cache for field definitions.
    *
-   * @see self::getPropertyDefinitions()
+   * @see EntityNG::getPropertyDefinitions()
    *
    * @var array
    */
@@ -109,14 +110,14 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityInterface::id().
+   * Implements \Drupal\Core\Entity\EntityInterface::id().
    */
   public function id() {
     return $this->id->value;
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityInterface::bundle().
+   * Implements \Drupal\Core\Entity\EntityInterface::bundle().
    */
   public function bundle() {
     return $this->bundle;
@@ -130,7 +131,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * 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 +148,14 @@ class EntityNG extends Entity {
    * @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 speed-up 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 +171,14 @@ class EntityNG extends Entity {
   }
 
   /**
-   * 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 +191,14 @@ class EntityNG extends Entity {
   }
 
   /**
-   * 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 +213,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
     if (!isset($this->fieldDefinitions)) {
@@ -225,7 +226,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyValues().
    */
   public function getPropertyValues() {
     $values = array();
@@ -236,7 +237,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements ComplexDataInterface::setPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::setPropertyValues().
    */
   public function setPropertyValues($values) {
     foreach ($values as $name => $value) {
@@ -245,7 +246,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements ComplexDataInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::isEmpty().
    */
   public function isEmpty() {
     if (!$this->isNew()) {
@@ -260,7 +261,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements TranslatableInterface::language().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::language().
    */
   public function language() {
     $language = $this->get('langcode')->language;
@@ -272,7 +273,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements TranslatableInterface::getTranslation().
+   * Implements \Drupal\Core\TypedData\TranslatableInterface::getTranslation().
    *
    * @return \Drupal\Core\Entity\Field\Type\EntityTranslation
    */
@@ -315,12 +316,12 @@ class EntityNG extends Entity {
   }
 
   /**
-   * 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()) {
@@ -328,6 +329,8 @@ class EntityNG extends Entity {
         }
         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;
             }
@@ -335,12 +338,14 @@ class EntityNG extends Entity {
         }
       }
     }
+    // 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);
   }
 
@@ -386,6 +391,8 @@ class EntityNG extends Entity {
    * 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];
     }
@@ -402,8 +409,8 @@ class EntityNG extends Entity {
     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;
     }
@@ -420,7 +427,8 @@ class EntityNG extends Entity {
     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);
     }
@@ -475,7 +483,7 @@ class EntityNG extends Entity {
   }
 
   /**
-   * Implements a deep clone.
+   * Magic method: Implements a deep clone.
    */
   public function __clone() {
     $this->bcEntity = NULL;

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;
@@ -25,7 +25,7 @@ class EntityRenderController implements EntityRenderControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityRenderControllerInterface::buildContent().
+   * Implements \Drupal\Core\Entity\EntityRenderControllerInterface::buildContent().
    */
   public function buildContent(array $entities, array $displays, $view_mode, $langcode = NULL) {
     field_attach_prepare_view($this->entityType, $entities, $displays, $langcode);
@@ -43,7 +43,7 @@ class EntityRenderController implements EntityRenderControllerInterface {
   /**
    * 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.
@@ -82,7 +82,7 @@ class EntityRenderController implements EntityRenderControllerInterface {
   protected function alterBuild(array &$build, EntityInterface $entity, EntityDisplay $display, $view_mode, $langcode = NULL) { }
 
   /**
-   * Implements Drupal\Core\Entity\EntityRenderControllerInterface::view().
+   * Implements \Drupal\Core\Entity\EntityRenderControllerInterface::view().
    */
   public function view(EntityInterface $entity, $view_mode = 'full', $langcode = NULL) {
     $buildList = $this->viewMultiple(array($entity), $view_mode, $langcode);
@@ -90,7 +90,7 @@ class EntityRenderController implements EntityRenderControllerInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\EntityRenderControllerInterface::viewMultiple().
+   * Implements \Drupal\Core\Entity\EntityRenderControllerInterface::viewMultiple().
    */
   public function viewMultiple(array $entities = array(), $view_mode = 'full', $langcode = NULL) {
     if (!isset($langcode)) {

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;
@@ -34,7 +34,7 @@ interface EntityRenderControllerInterface {
   /**
    * 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.

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 @@ interface EntityStorageControllerInterface {
    * @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 @@ interface EntityStorageControllerInterface {
    *   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 @@ interface EntityStorageControllerInterface {
    * @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 @@ interface EntityStorageControllerInterface {
   /**
    * 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);

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;

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 @@ use Drupal\Core\TypedData\TypedDataInterface;
 /**
  * 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
@@ -30,50 +30,49 @@ use Drupal\Core\TypedData\TypedDataInterface;
 interface FieldInterface extends ListInterface, AccessibleInterface, ContextAwareInterface, TypedDataInterface {
 
   /**
-   * Delegates to the first item.
+   * Gets a property object from the first field item.
    *
    * @see \Drupal\Core\Entity\Field\FieldItemInterface::get()
    */
   public function get($property_name);
 
   /**
-   * Magic getter: Delegates to the first item.
+   * Magic method: Gets a property value of to the first field item.
    *
    * @see \Drupal\Core\Entity\Field\FieldItemInterface::__get()
    */
   public function __get($property_name);
 
   /**
-   * Magic setter: Delegates to the first item.
+   * Magic method: Sets a property value of the first field item.
    *
    * @see \Drupal\Core\Entity\Field\FieldItemInterface::__set()
    */
   public function __set($property_name, $value);
 
   /**
-   * Magic method for isset(): Delegates to the first item.
+   * Magic method: Determines whether a property of the first field item is set.
    *
    * @see \Drupal\Core\Entity\Field\FieldItemInterface::__isset()
    */
   public function __isset($property_name);
 
   /**
-   * Magic method for unset(): Delegates to the first item.
+   * Magic method: Unsets a property of the first field item.
    *
    * @see \Drupal\Core\Entity\Field\FieldItemInterface::__unset()
    */
   public function __unset($property_name);
 
-
   /**
-   * Delegates to the first item.
+   * Gets the definition of a property of the first field item.
    *
    * @see \Drupal\Core\Entity\Field\FieldItemInterface::getPropertyDefinition()
    */
   public function getPropertyDefinition($name);
 
   /**
-   * Delegates to the first item.
+   * Gets an array of property definitions of the first field item.
    *
    * @see \Drupal\Core\Entity\Field\FieldItemInterface::getPropertyDefinitions()
    */

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;
@@ -26,13 +26,13 @@ use InvalidArgumentException;
 abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAggregate, FieldItemInterface {
 
   /**
-   * The array of properties.
+   * The array of properties, each implementing the TypedDataInterface.
    *
    * Field objects are instantiated during object construction and cannot be
    * replaced by others, so computed properties can safely store references on
    * other properties.
    *
-   * @var array<TypedDataInterface>
+   * @var array
    */
   protected $properties = array();
 
@@ -61,7 +61,7 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides \Drupal\Core\TypedData\TypedData::getValue().
    */
   public function getValue() {
     $values = array();
@@ -72,9 +72,9 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides \Drupal\Core\TypedData\TypedData::setValue().
    *
-   * @param array $values
+   * @param array|null $values
    *   An array of property values.
    */
   public function setValue($values) {
@@ -98,7 +98,7 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides \Drupal\Core\TypedData\TypedData::getString().
    */
   public function getString() {
     $strings = array();
@@ -109,14 +109,7 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // @todo implement
-  }
-
-  /**
-   * Implements ComplexDataInterface::get().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::get().
    */
   public function get($property_name) {
     if (!isset($this->properties[$property_name])) {
@@ -126,21 +119,21 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements ComplexDataInterface::set().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::set().
    */
   public function set($property_name, $value) {
     $this->get($property_name)->setValue($value);
   }
 
   /**
-   * Implements FieldItemInterface::__get().
+   * Implements \Drupal\Core\Entity\Field\FieldItemInterface::__get().
    */
   public function __get($name) {
     return $this->get($name)->getValue();
   }
 
   /**
-   * Implements FieldItemInterface::__set().
+   * Implements \Drupal\Core\Entity\Field\FieldItemInterface::__set().
    */
   public function __set($name, $value) {
     // Support setting values via property objects.
@@ -151,14 +144,14 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements FieldItemInterface::__isset().
+   * Implements \Drupal\Core\Entity\Field\FieldItemInterface::__isset().
    */
   public function __isset($name) {
     return isset($this->properties[$name]) && $this->properties[$name]->getValue() !== NULL;
   }
 
   /**
-   * Implements FieldItemInterface::__unset().
+   * Implements \Drupal\Core\Entity\Field\FieldItemInterface::__unset().
    */
   public function __unset($name) {
     if (isset($this->properties[$name])) {
@@ -166,9 +159,8 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
     }
   }
 
-
   /**
-   * Implements ComplexDataInterface::getProperties().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getProperties().
    */
   public function getProperties($include_computed = FALSE) {
     $properties = array();
@@ -181,14 +173,14 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * 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 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * 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 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements ComplexDataInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::isEmpty().
    */
   public function isEmpty() {
     foreach ($this->getProperties() as $property) {
@@ -229,7 +221,7 @@ abstract class FieldItemBase extends ContextAwareTypedData implements IteratorAg
   }
 
   /**
-   * Implements a deep clone.
+   * Magic method: Implements a deep clone.
    */
   public function __clone() {
     foreach ($this->properties as $name => $property) {

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\ContextAwareInterface;
 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 @@ use Drupal\Core\TypedData\TypedDataInterface;
 interface FieldItemInterface extends ComplexDataInterface, ContextAwareInterface, TypedDataInterface {
 
   /**
-   * Magic getter: Get the property value.
+   * Magic method: Gets a property value.
    *
    * @param $property_name
    *   The name of the property to get; e.g., 'title' or 'name'.
@@ -38,7 +40,7 @@ interface FieldItemInterface extends ComplexDataInterface, ContextAwareInterface
   public function __get($property_name);
 
   /**
-   * Magic setter: Set the property value.
+   * Magic method: Sets a property value.
    *
    * @param $property_name
    *   The name of the property to set; e.g., 'title' or 'name'.
@@ -53,7 +55,7 @@ interface FieldItemInterface extends ComplexDataInterface, ContextAwareInterface
   public function __set($property_name, $value);
 
   /**
-   * Magic method for isset().
+   * Magic method: Determines whether a property is set.
    *
    * @param $property_name
    *   The name of the property to get; e.g., 'title' or 'name'.
@@ -64,7 +66,7 @@ interface FieldItemInterface extends ComplexDataInterface, ContextAwareInterface
   public function __isset($property_name);
 
   /**
-   * Magic method for unset().
+   * Magic method: Unsets a property.
    *
    * @param $property_name
    *   The name of the property to get; e.g., 'title' or 'name'.

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,23 +17,23 @@ class BooleanItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see BooleanItem::getPropertyDefinitions()
    *
    * @var array
    */
   static $propertyDefinitions;
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   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;
   }
 }

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,23 +17,23 @@ class DateItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see DateItem::getPropertyDefinitions()
    *
    * @var array
    */
   static $propertyDefinitions;
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   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;
   }
 }

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,26 +21,26 @@ class EntityReferenceItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see EntityReferenceItem::getPropertyDefinitions()
    *
    * @var array
    */
   static $propertyDefinitions;
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   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 @@ class EntityReferenceItem extends FieldItemBase {
         'settings' => array('id source' => 'value'),
       );
     }
-    return self::$propertyDefinitions[$entity_type];
+    return static::$propertyDefinitions[$entity_type];
   }
 
   /**
@@ -61,7 +61,7 @@ class EntityReferenceItem extends FieldItemBase {
    */
   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);
     }

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 IteratorAggregate;
 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 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides \Drupal\Core\TypedData\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 \Drupal\Core\TypedData\TypedData::setValue().
    */
   public function setValue($values) {
-    $this->properties = $values;
+    $this->fields = $values;
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides \Drupal\Core\TypedData\TypedData::getString().
    */
   public function getString() {
     $strings = array();
@@ -83,25 +87,25 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
   }
 
   /**
-   * Implements TypedDataInterface::get().
+   * Implements \Drupal\Core\TypedData\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];
   }
 
   /**
-   * 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();
@@ -114,28 +118,28 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
   }
 
   /**
-   * Magic getter: Gets the translated property.
+   * Magic method: Gets a translated field.
    */
   public function __get($name) {
     return $this->get($name);
   }
 
   /**
-   * Magic getter: Sets the translated property.
+   * Magic method: Sets a translated field.
    */
   public function __set($name, $value) {
     $this->get($name)->setValue($value);
   }
 
   /**
-   * 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();
@@ -148,7 +152,7 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
     $definitions = array();
@@ -161,14 +165,14 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
   }
 
   /**
-   * 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) {
@@ -177,7 +181,7 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
   }
 
   /**
-   * Implements ComplexDataInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::isEmpty().
    */
   public function isEmpty() {
     foreach ($this->getProperties() as $property) {
@@ -189,10 +193,12 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
   }
 
   /**
-   * Implements AccessibleInterface::access().
+   * Implements \Drupal\Core\TypedData\AccessibleInterface::access().
    */
   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.
     $langcode = substr($this->getName(), 1);
@@ -200,11 +206,4 @@ class EntityTranslation extends ContextAwareTypedData implements IteratorAggrega
       ->getAccessController($this->parent->entityType())
       ->$method($this->parent, $langcode, $account);
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate($value = NULL) {
-    // @todo implement
-  }
 }

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 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Overrides \Drupal\Core\TypedData\TypedData::getValue().
    */
   public function getValue() {
     $source = $this->getIdSource();
@@ -79,7 +79,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides \Drupal\Core\TypedData\TypedData::setValue().
    *
    * Both the entity ID and the entity object may be passed as value.
    */
@@ -92,7 +92,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
     elseif (isset($value) && !(is_scalar($value) && !empty($this->definition['constraints']['entity type']))) {
       throw new InvalidArgumentException('Value is not a 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 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Overrides \Drupal\Core\TypedData\TypedData::getString().
    */
   public function getString() {
     if ($entity = $this->getValue()) {
@@ -113,14 +113,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate($value = NULL) {
-    // TODO: Implement validate() method.
-  }
-
-  /**
-   * Implements IteratorAggregate::getIterator().
+   * Implements \IteratorAggregate::getIterator().
    */
   public function getIterator() {
     if ($entity = $this->getValue()) {
@@ -130,7 +123,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements ComplexDataInterface::get().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::get().
    */
   public function get($property_name) {
     // @todo: Allow navigating through the tree without data as well.
@@ -140,14 +133,14 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * 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) {
     if ($entity = $this->getValue()) {
@@ -157,7 +150,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinition().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinition().
    */
   public function getPropertyDefinition($name) {
     $definitions = $this->getPropertyDefinitions();
@@ -170,7 +163,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
     // @todo: Support getting definitions if multiple bundles are specified.
@@ -178,7 +171,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements ComplexDataInterface::getPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyValues().
    */
   public function getPropertyValues() {
     if ($entity = $this->getValue()) {
@@ -188,7 +181,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements ComplexDataInterface::setPropertyValues().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::setPropertyValues().
    */
   public function setPropertyValues($values) {
     if ($entity = $this->getValue()) {
@@ -197,7 +190,7 @@ class EntityWrapper extends ContextAwareTypedData implements IteratorAggregate,
   }
 
   /**
-   * Implements ComplexDataInterface::isEmpty().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::isEmpty().
    */
   public function isEmpty() {
     return (bool) $this->getValue();

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 IteratorAggregate;
 use InvalidArgumentException;
 
 /**
- * An entity field, i.e. a list of field items.
+ * Represents an entity field; that is, 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 \Drupal\Core\TypedData\TypedData::getValue().
    */
   public function getValue() {
     if (isset($this->list)) {
@@ -68,10 +68,10 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides \Drupal\Core\TypedData\TypedData::setValue().
    *
-   * @param array $values
-   *   An array of values of the field items.
+   * @param array|null $values
+   *   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 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * Returns a string representation of the field.
-   *
-   * @return string
+   * Overrides \Drupal\Core\TypedData\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,21 +117,14 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // @todo implement
-  }
-
-  /**
-   * Implements ArrayAccess::offsetExists().
+   * Implements \ArrayAccess::offsetExists().
    */
   public function offsetExists($offset) {
     return isset($this->list) && array_key_exists($offset, $this->list);
   }
 
   /**
-   * Implements ArrayAccess::offsetUnset().
+   * Implements \ArrayAccess::offsetUnset().
    */
   public function offsetUnset($offset) {
     if (isset($this->list)) {
@@ -142,7 +133,7 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * Implements ArrayAccess::offsetGet().
+   * Implements \ArrayAccess::offsetGet().
    */
   public function offsetGet($offset) {
     if (!is_numeric($offset)) {
@@ -166,14 +157,14 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * 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 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * Implements IteratorAggregate::getIterator().
+   * Implements \IteratorAggregate::getIterator().
    */
   public function getIterator() {
     if (isset($this->list)) {
@@ -203,63 +194,63 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * Implements Countable::count().
+   * Implements \Countable::count().
    */
   public function count() {
     return isset($this->list) ? count($this->list) : 0;
   }
 
   /**
-   * Delegate.
+   * Implements \Drupal\Core\Entity\Field\FieldInterface::getPropertyDefinition().
    */
   public function getPropertyDefinition($name) {
     return $this->offsetGet(0)->getPropertyDefinition($name);
   }
 
   /**
-   * Delegate.
+   * Implements \Drupal\Core\Entity\Field\FieldInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
     return $this->offsetGet(0)->getPropertyDefinitions();
   }
 
   /**
-   * Delegate.
+   * Implements \Drupal\Core\Entity\Field\FieldInterface::__get().
    */
   public function __get($property_name) {
     return $this->offsetGet(0)->get($property_name)->getValue();
   }
 
   /**
-   * Delegate.
+   * Implements \Drupal\Core\Entity\Field\FieldInterface::get().
    */
   public function get($property_name) {
     return $this->offsetGet(0)->get($property_name);
   }
 
   /**
-   * Delegate.
+   * Implements \Drupal\Core\Entity\Field\FieldInterface::__set().
    */
   public function __set($property_name, $value) {
     $this->offsetGet(0)->__set($property_name, $value);
   }
 
   /**
-   * Delegate.
+   * Implements \Drupal\Core\Entity\Field\FieldInterface::__isset().
    */
   public function __isset($property_name) {
     return $this->offsetGet(0)->__isset($property_name);
   }
 
   /**
-   * Delegate.
+   * Implements \Drupal\Core\Entity\Field\FieldInterface::__unset().
    */
   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 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * 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 @@ class Field extends ContextAwareTypedData implements IteratorAggregate, FieldInt
   }
 
   /**
-   * Implements AccessibleInterface::access().
+   * Implements \Drupal\Core\TypedData\AccessibleInterface::access().
    */
   public function access($operation = 'view', User $account = NULL) {
     // TODO: Implement access() method. Use item access.

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,23 +17,23 @@ class IntegerItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see IntegerItem::getPropertyDefinitions()
    *
    * @var array
    */
   static $propertyDefinitions;
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   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;
   }
 }

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,23 +18,23 @@ class LanguageItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see LanguageItem::getPropertyDefinitions()
    *
    * @var array
    */
   static $propertyDefinitions;
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   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 @@ class LanguageItem extends FieldItemBase {
         'settings' => array('langcode source' => 'value'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 
   /**
@@ -51,7 +51,8 @@ class LanguageItem extends FieldItemBase {
    */
   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);
     }

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,23 +17,23 @@ class StringItem extends FieldItemBase {
   /**
    * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see StringItem::getPropertyDefinitions()
    *
    * @var array
    */
   static $propertyDefinitions;
 
   /**
-   * Implements ComplexDataInterface::getPropertyDefinitions().
+   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
    */
   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;
   }
 }

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;
@@ -30,21 +30,21 @@ abstract class ConditionBase implements ConditionInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\ConditionInterface::getConjunction().
+   * Implements \Drupal\Core\Entity\Query\ConditionInterface::getConjunction().
    */
   public function getConjunction() {
     return $this->conjunction;
   }
 
   /**
-   * Implements Countable::count().
+   * Implements \Countable::count().
    */
   public function count() {
     return count($this->conditions) - 1;
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\ConditionInterface::compile().
+   * Implements \Drupal\Core\Entity\Query\ConditionInterface::compile().
    */
   public function condition($field, $value = NULL, $operator = NULL, $langcode = NULL) {
     $this->conditions[] = array(
@@ -58,7 +58,7 @@ abstract class ConditionBase implements ConditionInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\ConditionInterface::conditions().
+   * Implements \Drupal\Core\Entity\Query\ConditionInterface::conditions().
    */
   public function &conditions() {
     return $this->conditions;

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;
@@ -21,7 +21,7 @@ interface ConditionInterface {
   public function getConjunction();
 
   /**
-   * Implements Countable::count().
+   * Implements \Countable::count().
    *
    * Returns the size of this conditional. The size of the conditional is the
    * size of its conditional array minus one, because one element is the the

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;
@@ -84,14 +84,14 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::getEntityType().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::getEntityType().
    */
   public function getEntityType() {
     return $this->entityType;
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::condition().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::condition().
    */
   public function condition($property, $value = NULL, $operator = NULL, $langcode = NULL) {
     $this->condition->condition($property, $value, $operator, $langcode);
@@ -99,7 +99,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::exists().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::exists().
    */
   public function exists($property, $langcode = NULL) {
     $this->condition->exists($property, $langcode);
@@ -107,7 +107,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::notExists().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::notExists().
    */
   public function notExists($property, $langcode = NULL) {
     $this->condition->notExists($property, $langcode);
@@ -115,7 +115,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::range().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::range().
    */
   public function range($start = NULL, $length = NULL) {
     $this->range = array(
@@ -126,21 +126,21 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::andConditionGroup().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::andConditionGroup().
    */
   public function andConditionGroup() {
     return $this->conditionGroupFactory('and');
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::orConditionGroup().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::orConditionGroup().
    */
   public function orConditionGroup() {
     return $this->conditionGroupFactory('or');
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::sort().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::sort().
    */
   public function sort($property, $direction = 'ASC', $langcode = NULL) {
     $this->sort[$property] = array(
@@ -151,7 +151,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::count().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::count().
    */
   public function count() {
     $this->count = TRUE;
@@ -159,7 +159,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::accessCheck().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::accessCheck().
    */
   public function accessCheck($access_check = TRUE) {
     $this->accessCheck = $access_check;
@@ -167,7 +167,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::age().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::age().
    */
   public function age($age = FIELD_LOAD_CURRENT) {
     $this->age = $age;
@@ -175,7 +175,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::pager().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::pager().
    */
   public function pager($limit = 10, $element = NULL) {
     // Even when not using SQL, storing the element PagerSelectExtender is as
@@ -212,7 +212,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Entity\Query\QueryInterface::tableSort().
+   * Implements \Drupal\Core\Entity\Query\QueryInterface::tableSort().
    */
   public function tableSort(&$headers) {
     // If 'field' is not initialized, the header columns aren't clickable.
@@ -241,7 +241,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Database\Query\AlterableInterface::addTag().
+   * Implements \Drupal\Core\Database\Query\AlterableInterface::addTag().
    */
   public function addTag($tag) {
     $this->alterTags[$tag] = 1;
@@ -249,28 +249,28 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Database\Query\AlterableInterface::hasTag().
+   * Implements \Drupal\Core\Database\Query\AlterableInterface::hasTag().
    */
   public function hasTag($tag) {
     return isset($this->alterTags[$tag]);
   }
 
   /**
-   * Implements Drupal\Core\Database\Query\AlterableInterface::hasAllTags().
+   * Implements \Drupal\Core\Database\Query\AlterableInterface::hasAllTags().
    */
   public function hasAllTags() {
     return !(boolean)array_diff(func_get_args(), array_keys($this->alterTags));
   }
 
   /**
-   * Implements Drupal\Core\Database\Query\AlterableInterface::hasAnyTag().
+   * Implements \Drupal\Core\Database\Query\AlterableInterface::hasAnyTag().
    */
   public function hasAnyTag() {
     return (boolean)array_intersect(func_get_args(), array_keys($this->alterTags));
   }
 
   /**
-   * Implements Drupal\Core\Database\Query\AlterableInterface::addMetaData().
+   * Implements \Drupal\Core\Database\Query\AlterableInterface::addMetaData().
    */
   public function addMetaData($key, $object) {
     $this->alterMetaData[$key] = $object;
@@ -278,7 +278,7 @@ abstract class QueryBase implements QueryInterface {
   }
 
   /**
-   * Implements Drupal\Core\Database\Query\AlterableInterface::getMetaData().
+   * Implements \Drupal\Core\Database\Query\AlterableInterface::getMetaData().
    */
   public function getMetaData($key) {
     return isset($this->alterMetaData[$key]) ? $this->alterMetaData[$key] : NULL;

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;

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;

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;

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;

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;
@@ -101,7 +101,7 @@ interface ComplexDataInterface extends Traversable  {
   public function getPropertyDefinition($name);
 
   /**
-   * Gets an array property definitions of contained properties.
+   * Gets an array of property definitions of contained properties.
    *
    * @param array $definition
    *   The definition of the container's property, e.g. the definition of an

core/lib/Drupal/Core/TypedData/ContextAwareTypedData.php

@@ -12,7 +12,7 @@ namespace Drupal\Core\TypedData;
  *
  * 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().
@@ -53,7 +53,7 @@ abstract class ContextAwareTypedData extends TypedData implements ContextAwareIn
   }
 
   /**
-   * Implements ContextAwareInterface::setContext().
+   * Implements \Drupal\Core\TypedData\ContextAwareInterface::setContext().
    */
   public function setContext($name = NULL, ContextAwareInterface $parent = NULL) {
     $this->parent = $parent;
@@ -61,30 +61,35 @@ abstract class ContextAwareTypedData extends TypedData implements ContextAwareIn
   }
 
   /**
-   * Implements ContextAwareInterface::getName().
+   * Implements \Drupal\Core\TypedData\ContextAwareInterface::getName().
    */
   public function getName() {
     return $this->name;
   }
 
   /**
-   * Implements ContextAwareInterface::getRoot().
+   * Implements \Drupal\Core\TypedData\ContextAwareInterface::getRoot().
    */
   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;
   }
 
   /**
-   * Implements ContextAwareInterface::getPropertyPath().
+   * Implements \Drupal\Core\TypedData\ContextAwareInterface::getPropertyPath().
    */
   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;
     }
@@ -92,18 +97,11 @@ abstract class ContextAwareTypedData extends TypedData implements ContextAwareIn
   }
 
   /**
-   * Implements ContextAwareInterface::getParent().
+   * Implements \Drupal\Core\TypedData\ContextAwareInterface::getParent().
    *
    * @return \Drupal\Core\Entity\Field\FieldInterface
    */
   public function getParent() {
     return $this->parent;
   }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // @todo: Implement validate() method.
-  }
 }

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;

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 @@ final class Primitive {
 
   /**
    * 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;
 }

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;

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;

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 @@ class Binary extends TypedData {
   }
 
   /**
-   * 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 @@ class Binary extends TypedData {
   }
 
   /**
-   * 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.
-  }
 }

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.
-  }
 }

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 @@ use InvalidArgumentException;
 /**
  * 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 @@ class Date extends TypedData {
       }
     }
   }
-
-  /**
-   * Implements TypedDataInterface::getString().
-   */
-  public function getString() {
-    return (string) $this->getValue();
-  }
-
-  /**
-   * Implements TypedDataInterface::validate().
-   */
-  public function validate() {
-    // TODO: Implement validate() method.
-  }
 }

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 @@ class Duration extends TypedData {
   }
 
   /**
-   * 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.
-  }
 }

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.
-  }
 }

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.
-  }
 }

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 @@ use Drupal\Core\TypedData\ContextAwareTypedData;
  * 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 @@ class Language extends ContextAwareTypedData {
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Overrides TypedData::setValue().
    *
    * Both the langcode and the language object may be passed as value.
    */
@@ -66,7 +66,7 @@ class Language extends ContextAwareTypedData {
     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 @@ class Language extends ContextAwareTypedData {
   }
 
   /**
-   * 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.
-  }
 }

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.
-  }
 }

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.
-  }
 }

core/lib/Drupal/Core/TypedData/TypedData.php

@@ -35,37 +35,44 @@ abstract class TypedData implements TypedDataInterface {
   }
 
   /**
-   * Implements TypedDataInterface::getType().
+   * Implements \Drupal\Core\TypedData\TypedDataInterface::getType().
    */
   public function getType() {
     return $this->definition['type'];
   }
 
   /**
-   * Implements TypedDataInterface::getDefinition().
+   * Implements \Drupal\Core\TypedData\TypedDataInterface::getDefinition().
    */
   public function getDefinition() {
     return $this->definition;
   }
 
   /**
-   * Implements TypedDataInterface::getValue().
+   * Implements \Drupal\Core\TypedData\TypedDataInterface::getValue().
    */
   public function getValue() {
     return $this->value;
   }
 
   /**
-   * Implements TypedDataInterface::setValue().
+   * Implements \Drupal\Core\TypedData\TypedDataInterface::setValue().
    */
   public function setValue($value) {
     $this->value = $value;
   }
 
   /**
-   * Implements TypedDataInterface::getString().
+   * Implements \Drupal\Core\TypedData\TypedDataInterface::getString().
    */
   public function getString() {
     return (string) $this->getValue();
   }
+
+  /**
+   * Implements \Drupal\Core\TypedData\TypedDataInterface::validate().
+   */
+  public function validate() {
+    // TODO: Implement validate() method.
+  }
 }

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;
@@ -20,7 +20,7 @@ use Drupal\Component\Plugin\Exception\PluginException;
 class TypedDataFactory extends DefaultFactory {
 
   /**
-   * Implements Drupal\Component\Plugin\Factory\FactoryInterface::createInstance().
+   * Implements \Drupal\Component\Plugin\Factory\FactoryInterface::createInstance().
    *
    * @param string $plugin_id
    *   The id of a plugin, i.e. the data type.
@@ -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 @@ class TypedDataFactory extends DefaultFactory {
       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];

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;
@@ -40,7 +40,7 @@ interface TypedDataInterface {
   /**
    * Sets the data value.
    *
-   * @param mixed $value
+   * @param mixed|null $value
    *   The value to set in the format as documented for the data type or NULL to
    *   unset the data value.
    *

core/lib/Drupal/Core/TypedData/TypedDataManager.php

@@ -30,7 +30,7 @@ class TypedDataManager extends PluginManagerBase {
   }
 
   /**
-   * Implements Drupal\Component\Plugin\PluginManagerInterface::createInstance().
+   * Implements \Drupal\Component\Plugin\PluginManagerInterface::createInstance().
    *
    * @param string $plugin_id
    *   The id of a plugin, i.e. the data type.
@@ -45,13 +45,14 @@ class TypedDataManager extends PluginManagerBase {
    *   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 @@ class TypedDataManager extends PluginManagerBase {
    *   - 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 @@ class TypedDataManager extends PluginManagerBase {
    *   ComplexDataInterface.
    *
    * @return \Drupal\Core\TypedData\TypedDataInterface
+   *   The instantiated typed data object.
    *
    * @see typed_data()
    * @see \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance()
@@ -179,6 +181,8 @@ class TypedDataManager extends PluginManagerBase {
     // 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 @@ class TypedDataManager extends PluginManagerBase {
       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);
     }

core/modules/email/lib/Drupal/email/Type/EmailItem.php

@@ -15,26 +15,25 @@ use Drupal\Core\Entity\Field\FieldItemBase;
 class EmailItem extends FieldItemBase {
 
   /**
-   * Property definitions of the contained properties.
+   * Definitions of the contained properties.
    *
-   * @see self::getPropertyDefinitions()
+   * @see EmailItem::getPropertyDefinitions()
    *
    * @var array
    */
   static $propertyDefinitions;
 
   /**
-   * Implements \Drupal\Core\TypedData\ComplexDataInterface::getPropertyDefinitions().
+   * Implements ComplexDataInterface::getPropertyDefinitions().
    */
   public function getPropertyDefinitions() {
 
-    if (!isset(self::$propertyDefinitions)) {
-      self::$propertyDefinitions['value'] = array(
+    if (!isset(static::$propertyDefinitions)) {
+      static::$propertyDefinitions['value'] = array(
         'type' => 'email',
         'label' => t('E-mail value'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
-
 }

core/modules/picture/lib/Drupal/picture/Plugin/Core/Entity/PictureMapping.php

@@ -95,7 +95,7 @@ class PictureMapping extends ConfigEntityBase {
   }
 
   /**
-   * Implements EntityInterface::createDuplicate().
+   * Implements \Drupal\Core\Entity\EntityInterface::createDuplicate().
    */
   public function createDuplicate() {
     return entity_create('picture_mapping', array(

core/modules/system/tests/modules/entity_test/lib/Drupal/entity_test/EntityTestAccessController.php

@@ -17,7 +17,7 @@ use Drupal\user\Plugin\Core\Entity\User;
 class EntityTestAccessController implements EntityAccessControllerInterface {
 
   /**
-   * Implements EntityAccessControllerInterface::viewAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::viewAccess().
    */
   public function viewAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     if ($langcode != LANGUAGE_DEFAULT) {
@@ -27,21 +27,21 @@ class EntityTestAccessController implements EntityAccessControllerInterface {
   }
 
   /**
-   * Implements EntityAccessControllerInterface::createAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::createAccess().
    */
   public function createAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     return TRUE;
   }
 
   /**
-   * Implements EntityAccessControllerInterface::updateAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::updateAccess().
    */
   public function updateAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     return TRUE;
   }
 
   /**
-   * Implements EntityAccessControllerInterface::deleteAccess().
+   * Implements \Drupal\Core\Entity\EntityAccessControllerInterface::deleteAccess().
    */
   public function deleteAccess(EntityInterface $entity, $langcode = LANGUAGE_DEFAULT, User $account = NULL) {
     return TRUE;

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 TaxonomyTermReferenceItem::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 @@ class TaxonomyTermReferenceItem extends FieldItemBase {
         'settings' => array('id source' => 'tid'),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 
   /**

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 @@ class TextItem extends FieldItemBase {
         ),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }

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 TextSummaryItem::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 @@ class TextSummaryItem extends TextItem {
         ),
       );
     }
-    return self::$propertyDefinitions;
+    return static::$propertyDefinitions;
   }
 }