commit f5ec74b410741b876d4c7fbbca2fa771847b38a3
Author: Wolfgang Ziegler // fago <nuppla@zites.net>
Date:   Thu Jan 23 19:59:07 2014 +0100

    Various small docu improvements.

diff --git a/core/lib/Drupal/Core/Entity/EntityDefinition.php b/core/lib/Drupal/Core/Entity/EntityDefinition.php
index 6b1d367..3d6ee9f 100644
--- a/core/lib/Drupal/Core/Entity/EntityDefinition.php
+++ b/core/lib/Drupal/Core/Entity/EntityDefinition.php
@@ -10,7 +10,7 @@
 use Drupal\Core\TypedData\ComplexDataDefinitionBase;
 
 /**
- * Class for describing entities.
+ * A typed data definition class for describing entities.
  */
 class EntityDefinition extends ComplexDataDefinitionBase implements EntityDefinitionInterface {
 
diff --git a/core/lib/Drupal/Core/Field/FieldItemDefinition.php b/core/lib/Drupal/Core/Field/FieldItemDefinition.php
index 28a2337..9884fad 100644
--- a/core/lib/Drupal/Core/Field/FieldItemDefinition.php
+++ b/core/lib/Drupal/Core/Field/FieldItemDefinition.php
@@ -11,7 +11,12 @@
 use Drupal\Core\TypedData\DataDefinition;
 
 /**
- * A class for defining field items.
+ * A typed data definition class for defining field items.
+ *
+ * This class is just a small wrapper around field definitions to expose
+ * metadata about field item's via the Typed Data API. As the work is done
+ * by the field definitions, this class does not benefit and thus does not
+ * extend from MapDefinition or ComplexDataDefinitionBase.
  */
 class FieldItemDefinition extends DataDefinition implements ComplexDataDefinitionInterface {
 
diff --git a/core/lib/Drupal/Core/TypedData/DataDefinition.php b/core/lib/Drupal/Core/TypedData/DataDefinition.php
index 89d9f4e..28b78ab 100644
--- a/core/lib/Drupal/Core/TypedData/DataDefinition.php
+++ b/core/lib/Drupal/Core/TypedData/DataDefinition.php
@@ -8,7 +8,7 @@
 namespace Drupal\Core\TypedData;
 
 /**
- * A class for defining data based on defined data types.
+ * A typed data definition class for defining data based on defined data types.
  */
 class DataDefinition implements DataDefinitionInterface, \ArrayAccess {
 
diff --git a/core/lib/Drupal/Core/TypedData/DataReferenceDefinition.php b/core/lib/Drupal/Core/TypedData/DataReferenceDefinition.php
index 4503fde..489b56f 100644
--- a/core/lib/Drupal/Core/TypedData/DataReferenceDefinition.php
+++ b/core/lib/Drupal/Core/TypedData/DataReferenceDefinition.php
@@ -8,7 +8,7 @@
 namespace Drupal\Core\TypedData;
 
 /**
- * A class for defining references.
+ * A typed data definition class for defining references.
  *
  * Note that this definition class assumes that the data type for referencing
  * a certain target type is named "{TARGET_TYPE}_reference".
diff --git a/core/lib/Drupal/Core/TypedData/ListDefinition.php b/core/lib/Drupal/Core/TypedData/ListDefinition.php
index 820603c..6b18f28 100644
--- a/core/lib/Drupal/Core/TypedData/ListDefinition.php
+++ b/core/lib/Drupal/Core/TypedData/ListDefinition.php
@@ -8,7 +8,7 @@
 namespace Drupal\Core\TypedData;
 
 /**
- * A class for defining data based on defined data types.
+ * A typed data definition class for defining lists.
  */
 class ListDefinition extends DataDefinition implements ListDefinitionInterface {
 
diff --git a/core/lib/Drupal/Core/TypedData/MapDefinition.php b/core/lib/Drupal/Core/TypedData/MapDefinition.php
index d848211..0d39b51 100644
--- a/core/lib/Drupal/Core/TypedData/MapDefinition.php
+++ b/core/lib/Drupal/Core/TypedData/MapDefinition.php
@@ -8,7 +8,7 @@
 namespace Drupal\Core\TypedData;
 
 /**
- * Data definition class for maps.
+ * A typed data definition class for defining maps.
  */
 class MapDefinition extends ComplexDataDefinitionBase {
 
diff --git a/core/modules/system/lib/Drupal/system/Tests/TypedData/TypedDataTest.php b/core/modules/system/lib/Drupal/system/Tests/TypedData/TypedDataTest.php
index e7e6f0a..97407bf 100644
--- a/core/modules/system/lib/Drupal/system/Tests/TypedData/TypedDataTest.php
+++ b/core/modules/system/lib/Drupal/system/Tests/TypedData/TypedDataTest.php
@@ -412,7 +412,7 @@ public function testTypedDataMaps() {
       'two' => 'zwei',
       'three' => 'drei',
     );
-    $definition = MapDefinition::create('map')
+    $definition = MapDefinition::create()
       ->setPropertyDefinition('one', DataDefinition::create('string'))
       ->setPropertyDefinition('two', DataDefinition::create('string'))
       ->setPropertyDefinition('three', DataDefinition::create('string'));