diff -u b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php --- b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php +++ b/core/lib/Drupal/Core/Entity/Field/FieldDefinitionInterface.php @@ -21,30 +21,33 @@ * is the same, then the same field definition object can be used to describe * both. * - * This interface is agnostic as to where the information about the field comes - * from, and whether it fully defines a concrete data object (e.g., - * $node_1->body), or whether it provides a best-guess definition for a data - * object that might come into existence later, and have a potentially different - * definition when it does. For example, field.module defines configuration - * entities "field_entity" and "field_instance" for allowing a site - * administrator to add site-specific fields to any entity type and bundle. The - * "field_entity" objects store configuration that is independent of which - * entity type and bundle the field is added to, while the "field_instance" - * objects store configuration that is specific to the entity type and bundle. - * The class that implements "field_instance" configuration entities also - * implements this interface, returning information from either itself, or from - * the corresponding "field_entity" configuration, as appropriate. Meanwhile, - * the class that implements "field_entity" configuration also implements this - * interface, for use by code that needs access to a bundle-agnostic field - * definition, such as when configuring a View that can return results across - * bundles. Then when the View runs, the code that displays the results can - * choose whether to use the bundle-agnostic definitions or the bundle-specific - * ones. + * It is up to the class implementing this interface to manage where the + * information comes from. For example, field.module provides an implementation + * based on two levels of configuration. It allows the site administrator to add + * custom fields to any entity type and bundle via the "field_entity" and + * "field_instance" configuration entities. The former for storing configuration + * that is independent of which entity type and bundle the field is added to, + * and the latter for storing configuration that is specific to the entity type + * and bundle. The class that implements "field_instance" configuration entities + * also implements this interface, returning information from either itself, or + * from the corresponding "field_entity" configuration, as appropriate. * - * A field definition could also be provided for a field that is not - * defined via the field.module configuration entities. For example, all of the - * "base" fields defined by an entity type, such as $node->title. - * @todo Expand on this when it is implemented: https://drupal.org/node/1949932. + * However, entity base fields, such as $node->title, are not managed by + * field.module and its "field_entity"/"field_instance" configuration entities. + * Therefore, their definitions are provided by different objects that implement + * this interface. + * @todo That is still in progress: https://drupal.org/node/1949932. Update this + * documentation with details when that's implemented. + * + * Field definitions may fully define a concrete data object (e.g., + * $node_1->body), or may provide a best-guess definition for a data object that + * might come into existence later. For example, $node_1->body and $node_2->body + * may have different definitions (e.g., if the node types are different). When + * adding the "body" field to a View that can return nodes of different types, + * the View can get a field definition that represents the "body" field + * abstractly, and present Views configuration options to the administrator + * based on that abstract definition, even though that abstract definition can + * differ from the concrete definition of any particular node's body field. */ interface FieldDefinitionInterface {