Issue #1943664 by joachim: Use new standards to document entity info callback functions

8 files changed, 100 insertions, 35 deletions

diff --git a/includes/common.inc b/includes/common.inc
index 27fa190e0..31923f28b 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -2086,6 +2086,9 @@ function _format_date_callback(array $matches = NULL, $new_langcode = NULL) {
 /**
  * Format a username.
  *
+ * This is also the label callback implementation of
+ * callback_entity_info_label() for user_entity_info().
+ *
  * By default, the passed-in object's 'name' property is used if it exists, or
  * else, the site-defined value for the 'anonymous' variable. However, a module
  * may override this by implementing hook_username_alter(&$name, $account).
diff --git a/modules/comment/comment.module b/modules/comment/comment.module
index 46115be04..a83069f63 100644
--- a/modules/comment/comment.module
+++ b/modules/comment/comment.module
@@ -152,7 +152,7 @@ function comment_node_type_load($name) {
 }
 
 /**
- * Entity URI callback.
+ * Implements callback_entity_info_uri().
  */
 function comment_uri($comment) {
   return array(
diff --git a/modules/field/tests/field_test.module b/modules/field/tests/field_test.module
index 37ea7b1dd..dc2023a74 100644
--- a/modules/field/tests/field_test.module
+++ b/modules/field/tests/field_test.module
@@ -204,10 +204,7 @@ function field_test_dummy_field_storage_query(EntityFieldQuery $query) {
 }
 
 /**
- * Entity label callback.
- *
- * @param $entity
- *   The entity object.
+ * Implements callback_entity_info_label().
  *
  * @return
  *   The label of the entity prefixed with "label callback".
diff --git a/modules/forum/forum.module b/modules/forum/forum.module
index 18d9a7ecc..575de36a2 100644
--- a/modules/forum/forum.module
+++ b/modules/forum/forum.module
@@ -233,6 +233,8 @@ function forum_entity_info_alter(&$info) {
 }
 
 /**
+ * Implements callback_entity_info_uri().
+ *
  * Entity URI callback used in forum_entity_info_alter().
  */
 function forum_uri($forum) {
diff --git a/modules/node/node.module b/modules/node/node.module
index 378193d2b..f20c22950 100644
--- a/modules/node/node.module
+++ b/modules/node/node.module
@@ -244,13 +244,7 @@ function node_field_display_node_alter(&$display, $context) {
 }
 
 /**
- * Entity URI callback.
- *
- * @param $node
- *   A node entity.
- *
- * @return array
- *   An array with 'path' as the key and the path to the node as its value.
+ * Implements callback_entity_info_uri().
  */
 function node_uri($node) {
   return array(
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index ce4fb5fe8..e82ac8967 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -84,25 +84,23 @@ function hook_hook_info_alter(&$hooks) {
  *     Defaults to TRUE.
  *   - load hook: The name of the hook which should be invoked by
  *     DrupalDefaultEntityController:attachLoad(), for example 'node_load'.
- *   - uri callback: A function taking an entity as argument and returning the
- *     URI elements of the entity, e.g. 'path' and 'options'. The actual entity
- *     URI can be constructed by passing these elements to url().
- *   - label callback: (optional) A function taking an entity and an entity type
- *     as arguments and returning the label of the entity. The entity label is
- *     the main string associated with an entity; for example, the title of a
- *     node or the subject of a comment. If there is an entity object property
- *     that defines the label, use the 'label' element of the 'entity keys'
- *     return value component to provide this information (see below). If more
- *     complex logic is needed to determine the label of an entity, you can
- *     instead specify a callback function here, which will be called to
- *     determine the entity label. See also the entity_label() function, which
- *     implements this logic.
- *   - language callback: (optional) A function taking an entity and an entity
- *     type as arguments and returning a language code. In most situations, when
- *     needing to determine this value, inspecting a property named after the
- *     'language' element of the 'entity keys' should be enough. The language
- *     callback is meant to be used primarily for temporary alterations of the
- *     property value: entity-defining modules are encouraged to always define a
+ *   - uri callback: The name of an implementation of
+ *     callback_entity_info_uri().
+ *   - label callback: (optional) The name of an implementation of
+ *     callback_entity_info_label(), which returns the label of the entity. The
+ *     entity label is the main string associated with an entity; for example,
+ *     the title of a node or the subject of a comment. If there is an entity
+ *     object property that defines the label, then using the 'label' element of
+ *     the 'entity keys' return value component suffices to provide this
+ *     information (see below). Alternatively, specifying this callback allows
+ *     more complex logic to determine the label of an entity. See also the
+ *     entity_label() function, which implements this logic.
+ *   - language callback: (optional) The name of an implementation of
+ *     callback_entity_info_language(). In most situations, when needing to
+ *     determine this value, inspecting a property named after the 'language'
+ *     element of the 'entity keys' should be enough. The language callback is
+ *     meant to be used primarily for temporary alterations of the property
+ *     value: entity-defining modules are encouraged to always define a
  *     language property, instead of using the callback as main entity language
  *     source. In fact not having a language property defined is likely to
  *     prevent an entity from being queried by language. Moreover, given that
@@ -2302,7 +2300,7 @@ function hook_theme_registry_alter(&$theme_registry) {
  * @return
  *   The machine-readable name of the theme that should be used for the current
  *   page request. The value returned from this function will only have an
- *   effect if it corresponds to a currently-active theme on the site. Do not 
+ *   effect if it corresponds to a currently-active theme on the site. Do not
  *   return a value if you do not wish to set a custom theme.
  */
 function hook_custom_theme() {
@@ -3639,7 +3637,7 @@ function hook_registry_files_alter(&$files, $modules) {
  * inspect later. It is important to remove any temporary variables using
  * variable_del() before your last task has completed and control is handed
  * back to the installer.
- * 
+ *
  * @param array $install_state
  *   An array of information about the current installation state.
  *
@@ -4690,6 +4688,77 @@ function hook_filetransfer_info_alter(&$filetransfer_info) {
  */
 
 /**
+ * @addtogroup callbacks
+ * @{
+ */
+
+/**
+ * Return the URI for an entity.
+ *
+ * Callback for hook_entity_info().
+ *
+ * @param $entity
+ *   The entity to return the URI for.
+ *
+ * @return
+ *   An associative array with the following elements:
+ *   - 'path': The URL path for the entity.
+ *   - 'options': (optional) An array of options for the url() function.
+ *   The actual entity URI can be constructed by passing these elements to
+ *   url().
+ */
+function callback_entity_info_uri($entity) {
+  return array(
+    'path' => 'node/' . $entity->nid,
+  );
+}
+
+/**
+ * Return the label of an entity.
+ *
+ * Callback for hook_entity_info().
+ *
+ * @param $entity
+ *   The entity for which to generate the label.
+ * @param $entity_type
+ *   The entity type; e.g., 'node' or 'user'.
+ *
+ * @return
+ *   An unsanitized string with the label of the entity.
+ *
+ * @see entity_label()
+ */
+function callback_entity_info_label($entity, $entity_type) {
+  return empty($entity->title) ? 'Untitled entity' : $entity->title;
+}
+
+/**
+ * Return the language code of the entity.
+ *
+ * Callback for hook_entity_info().
+ *
+ * The language callback is meant to be used primarily for temporary alterations
+ * of the property value.
+ *
+ * @param $entity
+ *   The entity for which to return the language.
+ * @param $entity_type
+ *   The entity type; e.g., 'node' or 'user'.
+ *
+ * @return
+ *   The language code for the language of the entity.
+ *
+ * @see entity_language()
+ */
+function callback_entity_info_language($entity, $entity_type) {
+  return $entity->language;
+}
+
+/**
+ * @} End of "addtogroup callbacks".
+ */
+
+/**
  * @defgroup update_api Update versions of API functions
  * @{
  * Functions that are similar to normal API functions, but do not invoke hooks.
diff --git a/modules/taxonomy/taxonomy.module b/modules/taxonomy/taxonomy.module
index 9be7dfcbe..7ad28e9f2 100644
--- a/modules/taxonomy/taxonomy.module
+++ b/modules/taxonomy/taxonomy.module
@@ -140,7 +140,7 @@ function taxonomy_entity_info() {
 }
 
 /**
- * Entity URI callback.
+ * Implements callback_entity_info_uri().
  */
 function taxonomy_term_uri($term) {
   return array(
diff --git a/modules/user/user.module b/modules/user/user.module
index c1c7ec218..bff6f7623 100644
--- a/modules/user/user.module
+++ b/modules/user/user.module
@@ -187,7 +187,7 @@ function user_entity_info() {
 }
 
 /**
- * Entity URI callback.
+ * Implements callback_entity_info_uri().
  */
 function user_uri($user) {
   return array(