commit 0394cb07615326d88d3d52349a7d54c04ab73cc2
Author: fago <nuppla@zites.net>
Date:   Thu Dec 20 12:08:26 2012 +0100

    Documentation improvements.

diff --git a/core/lib/Drupal/Core/Entity/EntityBCDecorator.php b/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
index 2005bc0..c8911bd 100644
--- a/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
+++ b/core/lib/Drupal/Core/Entity/EntityBCDecorator.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Entity\EntityBCDecorator.
+ * Contains \Drupal\Core\Entity\EntityBCDecorator.
  */
 
 namespace Drupal\Core\Entity;
@@ -58,7 +58,9 @@ public function getBCEntity() {
   }
 
   /**
-   * Allows direct access to the plain values, as done in Drupal 7.
+   * Implements the magic method for getting object properties.
+   *
+   * Directly accesses the plain field values, as done in Drupal 7.
    */
   public function &__get($name) {
     // Make sure $this->decorated->values reflects the latest values.
@@ -84,7 +86,9 @@ public function &__get($name) {
   }
 
   /**
-   * Allows directly writing to the plain values, as done in Drupal 7.
+   * Implements the magic method for setting object properties.
+   *
+   * Directly writes to the plain field values, as done by Drupal 7.
    */
   public function __set($name, $value) {
     if (is_array($value) && $definition = $this->decorated->getPropertyDefinition($name)) {
@@ -102,7 +106,7 @@ public function __set($name, $value) {
   }
 
   /**
-   * Magic method.
+   * Implements the magic method for isset().
    */
   public function __isset($name) {
     $value = $this->__get($name);
@@ -110,7 +114,7 @@ public function __isset($name) {
   }
 
   /**
-   * Magic method.
+   * Implements the magic method for unset().
    */
   public function __unset($name) {
     $value = &$this->__get($name);
diff --git a/core/lib/Drupal/Core/Entity/EntityInterface.php b/core/lib/Drupal/Core/Entity/EntityInterface.php
index de405e1..69372e2 100644
--- a/core/lib/Drupal/Core/Entity/EntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityInterface.php
@@ -194,18 +194,20 @@ public function getExportProperties();
   /**
    * Gets a backward compatibility decorator entity.
    *
-   * @see \Drupal\Core\Entity\EntityInterface::getOriginalEntity()
-   *
    * @return \Drupal\Core\Entity\EntityInterface
+   *   The backward compatible entity.
+   *
+   * @see \Drupal\Core\Entity\EntityInterface::getOriginalEntity()
    */
   public function getBCEntity();
 
   /**
    * Removes any possibly (backward compatibility) decorator in use.
    *
-   * @see \Drupal\Core\Entity\EntityInterface::getBCEntity()
-   *
    * @return \Drupal\Core\Entity\EntityInterface
+   *   The original, not backward compatible entity object.
+   *
+   * @see \Drupal\Core\Entity\EntityInterface::getBCEntity()
    */
   public function getOriginalEntity();
 }
diff --git a/core/lib/Drupal/Core/Entity/EntityNG.php b/core/lib/Drupal/Core/Entity/EntityNG.php
index 5aee3bc..46e24af 100644
--- a/core/lib/Drupal/Core/Entity/EntityNG.php
+++ b/core/lib/Drupal/Core/Entity/EntityNG.php
@@ -381,8 +381,9 @@ public function updateOriginalValues() {
   }
 
   /**
-   * Magic getter: Gets the property in default language.
+   * Implements the magic method for setting object properties.
    *
+   * Uses default language always.
    * For compatibility mode to work this must return a reference.
    */
   public function &__get($name) {
@@ -411,7 +412,9 @@ public function &__get($name) {
   }
 
   /**
-   * Magic getter: Sets the property in default language.
+   * Implements the magic method for setting object properties.
+   *
+   * Uses default language always.
    */
   public function __set($name, $value) {
     // Support setting values via property objects.
@@ -433,7 +436,7 @@ public function __set($name, $value) {
   }
 
   /**
-   * Magic method.
+   * Implements the magic method for isset().
    */
   public function __isset($name) {
     if ($this->getPropertyDefinition($name)) {
@@ -445,7 +448,7 @@ public function __isset($name) {
   }
 
   /**
-   * Magic method.
+   * Implements the magic method for unset.
    */
   public function __unset($name) {
     if ($this->getPropertyDefinition($name)) {
diff --git a/core/modules/system/lib/Drupal/system/Tests/Entity/EntityTranslationTest.php b/core/modules/system/lib/Drupal/system/Tests/Entity/EntityTranslationTest.php
index b41bf3d..370622d 100644
--- a/core/modules/system/lib/Drupal/system/Tests/Entity/EntityTranslationTest.php
+++ b/core/modules/system/lib/Drupal/system/Tests/Entity/EntityTranslationTest.php
@@ -131,7 +131,7 @@ function testEntityLanguageMethods() {
       $this->pass('A translation for an invalid language is NULL.');
     }
 
-    // Try to get an unstranslatable value from a translation in strict mode.
+    // Try to get an untranslatable value from a translation in strict mode.
     try {
       $field_name = 'field_test_text';
       $value = $entity->getTranslation($this->langcodes[1])->get($field_name);
@@ -141,7 +141,7 @@ function testEntityLanguageMethods() {
       $this->pass('Getting an untranslatable value from a translation in strict mode throws an exception.');
     }
 
-    // Try to get an unstranslatable value from a translation in non-strict
+    // Try to get an untranslatable value from a translation in non-strict
     // mode.
     $entity->set($field_name, array(0 => array('value' => 'default value')));
     $value = $entity->getTranslation($this->langcodes[1], FALSE)->get($field_name)->value;
@@ -156,7 +156,7 @@ function testEntityLanguageMethods() {
       $this->pass("Setting a translation for an invalid language throws an exception.");
     }
 
-    // Try to set an unstranslatable value into a translation in strict mode.
+    // Try to set an untranslatable value into a translation in strict mode.
     try {
       $entity->getTranslation($this->langcodes[1])->set($field_name, NULL);
       $this->fail("Setting an untranslatable value into a translation in strict mode throws an exception.");