commit 1df4b1f606d7db984a051d0ff3da0909a3807812
Author: fago <nuppla@gmx.at>
Date:   Sun Aug 31 14:23:58 2014 +0200

    Adressed review.

diff --git a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
index 672f68c..551fc08 100644
--- a/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/ContentEntityInterface.php
@@ -12,6 +12,17 @@
 /**
  * Defines a common interface for all content entity objects.
  *
+ * Content entities use fields for all their entity properties and are
+ * translatable and revisionable, while translations and revisions can be
+ * enabled per entity type. It's best practice to always implement
+ * ContentEntityInterface for content-like entities that should be stored in
+ * some database, and enable/disable revisions and translations as desired.
+ *
+ * When implementing this interface which extends Traversable, make sure to list
+ * IteratorAggregate or Iterator before this interface in the implements clause.
+ *
+ * @see \Drupal\Core\Entity\ContentEntityBase
+ *
  * @ingroup entity_api
  */
 interface ContentEntityInterface extends FieldableEntityInterface, RevisionableInterface, TranslatableInterface {
diff --git a/core/lib/Drupal/Core/Entity/EntityInterface.php b/core/lib/Drupal/Core/Entity/EntityInterface.php
index 4399d01..c2c1d48 100644
--- a/core/lib/Drupal/Core/Entity/EntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityInterface.php
@@ -11,6 +11,8 @@
 
 /**
  * Defines a common interface for all entity objects.
+ *
+ * @ingroup entity_api
  */
 interface EntityInterface extends AccessibleInterface {
 
diff --git a/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php b/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php
index 17861b7..1c36c51 100644
--- a/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php
+++ b/core/lib/Drupal/Core/Entity/FieldableEntityInterface.php
@@ -25,7 +25,7 @@
  * @see \Drupal\Core\TypedData\TypedDataManager
  * @see \Drupal\Core\Field\FieldItemListInterface
  *
- * @entity_api
+ * @ingroup entity_api
  */
 interface FieldableEntityInterface extends EntityInterface, ComplexDataInterface {
 
diff --git a/core/modules/comment/src/CommentInterface.php b/core/modules/comment/src/CommentInterface.php
index 628743e..e7a4ee9 100644
--- a/core/modules/comment/src/CommentInterface.php
+++ b/core/modules/comment/src/CommentInterface.php
@@ -7,7 +7,6 @@
 
 namespace Drupal\comment;
 
-use Drupal\Core\Entity\FieldableEntityInterface;
 use Drupal\Core\Entity\ContentEntityInterface;
 use Drupal\user\EntityOwnerInterface;
 use Drupal\Core\Entity\EntityChangedInterface;