Issue #2157467 by Xano, Berdir: Fix type hinting for base entity interfaces.

core/lib/Drupal/Core/Config/Entity/ConfigEntityInterface.php

@@ -61,14 +61,37 @@ public function setSyncing($status);
    *     checking and managing the status.
    *
    * @return bool
+   *   Whether the entity is enabled or not.
    */
   public function status();
 
   /**
-   * Returns whether the configuration entity is created, updated or deleted
-   * through the import process.
+   * Returns whether this entity is being changed as part of an import process.
+   *
+   * If you are writing code that responds to a change in this entity (insert,
+   * update, delete, presave, etc.), and your code would result in a
+   * configuration change (whether related to this configuration entity, another
+   * configuration entity, or non-entity configuration) or your code would
+   * result in a change to this entity itself, you need to check and see if this
+   * entity change is part of an import process, and skip executing your code if
+   * that is the case.
+   *
+   * For example, \Drupal\node\Entity\NodeType::postSave() adds the default body
+   * field to newly created node type configuration entities, which is a
+   * configuration change. You would not want this code to run during an import,
+   * because imported entities were already given the body field when they were
+   * originally created, and the imported configuration includes all of their
+   * currently-configured fields. On the other hand,
+   * \Drupal\field\Entity\Field::preSave() and the methods it calls make sure
+   * that the storage tables are created or updated for the field configuration
+   * entity, which is not a configuration change, and it must be done whether
+   * due to an import or not. So, the first method should check
+   * $entity->isSyncing() and skip executing if it returns TRUE, and the second
+   * should not perform this check.
    *
    * @return bool
+   *   TRUE if the configuration entity is being created, updated, or deleted
+   *   through the import process.
    */
   public function isSyncing();
 
@@ -98,7 +121,7 @@ public function isUninstalling();
    *   The name of the property that should be returned.
    *
    * @return mixed
-   *   The property, if existing, NULL otherwise.
+   *   The property if it exists, or NULL otherwise.
    */
   public function get($property_name);
 

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

@@ -223,7 +223,7 @@ public function postSave(EntityStorageInterface $storage, $update = TRUE);
    *
    * @param \Drupal\Core\Entity\EntityStorageInterface $storage
    *   The entity storage object.
-   * @param array $values
+   * @param mixed[] $values
    *   An array of values to set, keyed by property name. If the entity type has
    *   bundles the bundle key has to be specified.
    */
@@ -232,7 +232,7 @@ public static function preCreate(EntityStorageInterface $storage, array &$values
   /**
    * Acts on an entity after it is created but before hooks are invoked.
    *
-   * @param EntityStorageInterface $storage
+   * @param \Drupal\Core\Entity\EntityStorageInterface $storage
    *   The entity storage object.
    */
   public function postCreate(EntityStorageInterface $storage);
@@ -242,7 +242,7 @@ public function postCreate(EntityStorageInterface $storage);
    *
    * Used before the entities are deleted and before invoking the delete hook.
    *
-   * @param EntityStorageInterface $storage
+   * @param \Drupal\Core\Entity\EntityStorageInterface $storage
    *   The entity storage object.
    * @param \Drupal\Core\Entity\EntityInterface[] $entities
    *   An array of entities.
@@ -254,7 +254,7 @@ public static function preDelete(EntityStorageInterface $storage, array $entitie
    *
    * Used after the entities are deleted but before invoking the delete hook.
    *
-   * @param EntityStorageInterface $storage
+   * @param \Drupal\Core\Entity\EntityStorageInterface $storage
    *   The entity storage object.
    * @param \Drupal\Core\Entity\EntityInterface[] $entities
    *   An array of entities.
@@ -264,7 +264,7 @@ public static function postDelete(EntityStorageInterface $storage, array $entiti
   /**
    * Acts on loaded entities.
    *
-   * @param EntityStorageInterface $storage
+   * @param \Drupal\Core\Entity\EntityStorageInterface $storage
    *   The entity storage object.
    * @param \Drupal\Core\Entity\EntityInterface[] $entities
    *   An array of entities.
@@ -284,7 +284,7 @@ public function createDuplicate();
    * Returns the entity type definition.
    *
    * @return \Drupal\Core\Entity\EntityTypeInterface
-   *   Entity type definition.
+   *   The entity type definition.
    */
   public function getEntityType();
 
@@ -300,8 +300,8 @@ public function referencedEntities();
    * Returns the original ID.
    *
    * @return int|string|null
-   *   The original ID, if any. Entity types that do not support renames will
-   *   never have an original ID and will return NULL.
+   *   The original ID, or NULL if no ID was set or for entity types that do not
+   *   support renames.
    */
   public function getOriginalId();
 
@@ -319,7 +319,7 @@ public function setOriginalId($id);
   /**
    * Returns an array of all property values.
    *
-   * @return array
+   * @return mixed[]
    *   An array of property values, keyed by property name.
    */
   public function toArray();