Issue #1968970 by plach: Standardize module-provided entity info documentation...

Issue #1968970 by plach: Standardize module-provided entity info documentation and clean-up the @EntityType annotation.

core/lib/Drupal/Core/Entity/Annotation/EntityType.php

@@ -25,14 +25,6 @@ class EntityType extends Plugin {
    */
   public $entity_type_class = 'Drupal\Core\Entity\EntityType';
 
-  /**
-   * @todo content_translation_entity_info_alter() uses this but it is
-   *   undocumented. Fix in https://drupal.org/node/1968970.
-   *
-   * @var array
-   */
-  public $translation = array();
-
   /**
    * {@inheritdoc}
    */

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

@@ -9,6 +9,11 @@
 
 /**
  * Provides an interface for an entity type and its metadata.
+ *
+ * Additional information can be provided by modules: hook_entity_info() can be
+ * implemented to define new properties, while hook_entity_info_alter() can be
+ * implemented to alter existing data and fill-in defaults. Module-specific
+ * properties should be documented in the hook implementations defining them.
  */
 interface EntityTypeInterface {
 
@@ -193,9 +198,6 @@ public function getController($controller_type);
    *   - access: The name of the class that is used for access checks. The class
    *     must implement \Drupal\Core\Entity\EntityAccessControllerInterface.
    *     Defaults to \Drupal\Core\Entity\EntityAccessController.
-   *   - translation: The name of the controller class that should be used to
-   *     handle the translation process. The class must implement
-   *     \Drupal\content_translation\ContentTranslationControllerInterface.
    */
   public function getControllers();
 

core/modules/content_translation/content_translation.module

@@ -75,6 +75,30 @@ function content_translation_language_types_info_alter(array &$language_types) {
 
 /**
  * Implements hook_entity_info_alter().
+ *
+ * The content translation UI relies on the entity info to provide its features.
+ * See the documentation of hook_entity_info() in the Entity API documentation
+ * for more details on all the entity info keys that may be defined.
+ *
+ * To make Content Translation automatically support an entity type some keys
+ * may need to be defined, but none of them is required unless the entity path
+ * is different from the usual /ENTITY_TYPE/{ENTITY_TYPE} pattern (for instance
+ * "/taxonomy/term/{taxonomy_term}"), in which case at least the 'canonical' key
+ * in the 'links' entity info property must be defined.
+ *
+ * Every entity type needs a translation controller to be translated. This can
+ * be specified through the 'translation' key in the 'controllers' entity info
+ * property. If an entity type is translatable and no translation controller is
+ * defined, \Drupal\content_translation\ContentTranslationController will be
+ * assumed. Every translation controller class must implement
+ * \Drupal\content_translation\ContentTranslationControllerInterface.
+ *
+ * If the entity paths match the default pattern above and there is no need for
+ * an entity-specific translation controller class, Content Translation will
+ * provide built-in support for the entity. However enabling translation for
+ * each translatable bundle will be required.
+ *
+ * @see \Drupal\Core\Entity\Annotation\EntityType
  */
 function content_translation_entity_info_alter(array &$entity_info) {
   // Provide defaults for translation info.
@@ -95,6 +119,8 @@ function content_translation_entity_info_alter(array &$entity_info) {
         if (!$info->hasLinkTemplate('drupal:content-translation-overview')) {
           $info->setLinkTemplate('drupal:content-translation-overview', "content_translation.translation_overview_$entity_type");
         }
+        // @todo Remove this as soon as menu access checks rely on the
+        //   controller. See https://drupal.org/node/2155787.
         $translation['content_translation'] += array(
           'access_callback' => 'content_translation_translate_access',
         );

core/modules/content_translation/lib/Drupal/content_translation/ContentTranslationControllerInterface.php

@@ -14,31 +14,6 @@
  *
  * Defines a set of methods to allow any entity to be processed by the entity
  * translation UI.
- *
- * The content translation UI relies on the entity info to provide its features.
- * See the documentation of hook_entity_info() in the Entity API documentation
- * for more details on all the entity info keys that may be defined.
- *
- * To make Content Translation automatically support an entity type some keys
- * may need to be defined, but none of them is required unless the entity path
- * is different from ENTITY_TYPE/%ENTITY_TYPE (e.g. taxonomy/term/1), in which
- * case at least the 'canonical' key in the 'links' entity info property must be
- * defined.
- *
- * Every entity type needs a translation controller to be translated. This can
- * be specified through the "controllers['translation']" key in the entity
- * info. If an entity type is enabled for translation and no translation
- * controller is defined,
- * \Drupal\content_translation\ContentTranslationController will be assumed.
- * Every translation controller class must implement
- * \Drupal\content_translation\ContentTranslationControllerInterface.
- *
- * If the entity paths match the default patterns above and there is no need for
- * an entity-specific translation controller class, Content Translation will
- * provide built-in support for the entity. It will still be required to enable
- * translation for each translatable bundle.
- *
- * @see \Drupal\Core\Entity\EntityManagerInterface
  */
 interface ContentTranslationControllerInterface {
 

core/modules/system/entity.api.php

@@ -96,14 +96,14 @@ function hook_ENTITY_TYPE_create_access(\Drupal\Core\Session\AccountInterface $a
 /**
  * Add to entity type definitions.
  *
- * Modules may implement this hook to add information to defined entity types.
+ * Modules may implement this hook to add information to defined entity types,
+ * as defined in \Drupal\Core\Entity\EntityTypeInterface.
  *
  * @param \Drupal\Core\Entity\EntityTypeInterface $entity_info
  *   An associative array of all entity type definitions, keyed by the entity
  *   type name. Passed by reference.
  *
  * @see \Drupal\Core\Entity\Entity
- * @see \Drupal\Core\Entity\EntityManagerInterface
  * @see \Drupal\Core\Entity\EntityTypeInterface
  */
 function hook_entity_info(&$entity_info) {
@@ -113,6 +113,31 @@ function hook_entity_info(&$entity_info) {
   $entity_info['node']->setForm('mymodule_foo', 'Drupal\mymodule\NodeFooFormController');
 }
 
+/**
+ * Alter the entity type definitions.
+ *
+ * Modules may implement this hook to alter the information that defines an
+ * entity type. All properties that are available in
+ * \Drupal\Core\Entity\Annotation\EntityType and all the ones additionally
+ * provided by modules can be altered here.
+ *
+ * Do not use this hook to add information to entity types, unless you are just
+ * filling-in default values. Use hook_entity_info() instead.
+ *
+ * @param \Drupal\Core\Entity\EntityTypeInterface $entity_info
+ *   An associative array of all entity type definitions, keyed by the entity
+ *   type name. Passed by reference.
+ *
+ * @see \Drupal\Core\Entity\Entity
+ * @see \Drupal\Core\Entity\EntityTypeInterface
+ */
+function hook_entity_info_alter(&$entity_info) {
+  /** @var $entity_info \Drupal\Core\Entity\EntityTypeInterface[] */
+  // Set the controller class for nodes to an alternate implementation of the
+  // Drupal\Core\Entity\EntityStorageControllerInterface interface.
+  $entity_info['node']->setController('storage', 'Drupal\mymodule\MyCustomNodeStorageController');
+}
+
 /**
  * Alter the view modes for entity types.
  *
@@ -220,31 +245,6 @@ function hook_entity_bundle_delete($entity_type, $bundle) {
   }
 }
 
-/**
- * Alter the entity type definitions.
- *
- * Modules may implement this hook to alter the information that defines an
- * entity type. All properties that are available in
- * \Drupal\Core\Entity\EntityManagerInterface can be altered here.
- *
- * Do not use this hook to add information to entity types. Use
- * hook_entity_info() for that instead.
- *
- * @param \Drupal\Core\Entity\EntityTypeInterface $entity_info
- *   An associative array of all entity type definitions, keyed by the entity
- *   type name. Passed by reference.
- *
- * @see \Drupal\Core\Entity\Entity
- * @see \Drupal\Core\Entity\EntityManagerInterface
- * @see \Drupal\Core\Entity\EntityTypeInterface
- */
-function hook_entity_info_alter(&$entity_info) {
-  /** @var $entity_info \Drupal\Core\Entity\EntityTypeInterface[] */
-  // Set the controller class for nodes to an alternate implementation of the
-  // Drupal\Core\Entity\EntityStorageControllerInterface interface.
-  $entity_info['node']->setController('storage', 'Drupal\mymodule\MyCustomNodeStorageController');
-}
-
 /**
  * Act on a newly created entity.
  *