Issue #2980374 by joachim, ranjith_kumar_k_u, msankhala: Add an API docs topic...

Issue #2980374 by joachim, ranjith_kumar_k_u, msankhala: Add an API docs topic to cover entity characteristics in general and how they work

(cherry picked from commit 822dad38)

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

@@ -13,6 +13,8 @@
  * editing.
  *
  * @see \Drupal\Core\Entity\Plugin\Validation\Constraint\EntityChangedConstraint
+ *
+ * @ingroup entity_type_characteristics
  */
 interface EntityChangedInterface extends EntityInterface {
 

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

@@ -4,6 +4,8 @@
 
 /**
  * Provides an interface for access to an entity's published state.
+ *
+ * @ingroup entity_type_characteristics
  */
 interface EntityPublishedInterface extends EntityInterface {
 

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

@@ -6,6 +6,8 @@
 
 /**
  * Defines methods for an entity that supports revision logging and ownership.
+ *
+ * @ingroup entity_type_characteristics
  */
 interface RevisionLogInterface extends RevisionableInterface {
 

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

@@ -19,6 +19,8 @@
  * @see \Drupal\Core\Entity\EntityTypeInterface::isRevisionable()
  * @see https://www.drupal.org/docs/8/api/entity-api/structure-of-an-entity-annotation
  * @see https://www.drupal.org/docs/8/api/entity-api/making-an-entity-revisionable
+ *
+ * @ingroup entity_type_characteristics
  */
 interface RevisionableInterface extends EntityInterface {
 

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

@@ -6,6 +6,8 @@
 
 /**
  * Provides methods for an entity to support translation.
+ *
+ * @ingroup entity_type_characteristics
  */
 interface TranslatableInterface extends TranslatableDataInterface, EntityInterface {
 

core/lib/Drupal/Core/Entity/entity.api.php

@@ -119,6 +119,12 @@
  * @see \Drupal\Core\Entity\TranslatableRevisionableInterface
  * @see \Drupal\Core\Entity\TranslatableRevisionableStorageInterface
  *
+ * @section characteristics Entity characteristics
+ *
+ * In addition to entity interfaces for revisionable and translatable
+ * interfaces, there are interfaces for other kinds of entity functionality.
+ * @see entity_characteristics
+ *
  * @section create Create operations
  * To create an entity:
  * @code
@@ -354,7 +360,10 @@
  *   as short as possible, and may not exceed 32 characters.
  * - Define an interface for your entity's get/set methods, usually extending
  *   either \Drupal\Core\Config\Entity\ConfigEntityInterface or
- *   \Drupal\Core\Entity\ContentEntityInterface.
+ *   \Drupal\Core\Entity\ContentEntityInterface. Other interfaces that add
+ *   functionality are also available: see the
+ *   @link entity_characteristics Entity characteristics topic @endlink
+ *   for more information.
  * - Define a class for your entity, implementing your interface and extending
  *   either \Drupal\Core\Config\Entity\ConfigEntityBase or
  *   \Drupal\Core\Entity\ContentEntityBase, with annotation for
@@ -637,6 +646,31 @@
  * @}
  */
 
+/**
+ * @defgroup entity_type_characteristics Entity type characteristics
+ * @{
+ * Describes how to enhance entity types with additional functionality.
+ *
+ * When @link entity_api defining an entity type @endlink, the functionality of
+ * the entities can be enhanced with additional characteristics. Examples
+ * include entities that have a published/unpublished status, or a timestamp
+ * that gives the time they were last modified.
+ *
+ * These characteristics are provided by an interface, which the entity's own
+ * interface should inherit from, in addition to
+ * \Drupal\Core\Config\Entity\ConfigEntityInterface or
+ * \Drupal\Core\Entity\ContentEntityInterface.
+ *
+ * Some characteristics also provide a trait for the entity class. This has
+ * implementations of the interface's methods, and may also have a helper method
+ * for \Drupal\Core\Entity\EntityInterface::baseFieldsDefinition() which defines
+ * base fields that the trait expects to store data. Furthermore, trait methods
+ * may expect certain entity keys to be set: see the documentation for each
+ * trait for details.
+ *
+ * @}
+ */
+
 /**
  * @addtogroup hooks
  * @{

core/modules/user/src/EntityOwnerInterface.php

@@ -9,6 +9,8 @@
  * owners in Unix file system access. This may or may not be the entity's
  * original author. The owner may also have less permissions than other users,
  * such as administrators.
+ *
+ * @ingroup entity_type_characteristics
  */
 interface EntityOwnerInterface {