#977346 by jhodgdon, joachim: Fixed More detailed docs for entity_label

2 files changed, 19 insertions, 11 deletions

diff --git a/includes/common.inc b/includes/common.inc
index 938fcab03..4d6dddf2e 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -7464,13 +7464,16 @@ function entity_uri($entity_type, $entity) {
 /**
  * Returns the label of an entity.
  *
+ * See the 'label callback' component of the hook_entity_info() return value
+ * for more information.
+ *
  * @param $entity_type
- *   The entity type; e.g. 'node' or 'user'.
+ *   The entity type; e.g., 'node' or 'user'.
  * @param $entity
- *   The entity for which to generate a path.
+ *   The entity for which to generate the label.
  *
  * @return
- *   A string with the entity label (e.g. node title), or FALSE if not found.
+ *   The entity label, or FALSE if not found.
  */
 function entity_label($entity_type, $entity) {
   $label = FALSE;
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 4be4a7660..b9c8209cd 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -88,10 +88,15 @@ function hook_hook_info_alter(&$hooks) {
  *     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 as argument and
- *     returning the label of the entity; e.g., $node->title or
- *     $comment->subject. A callback should be specified when the label is the
- *     result of complex logic. Otherwise, the 'label' property of the
- *     'entity keys' the property should be used.
+ *     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.
  *   - fieldable: Set to TRUE if you want your entity type to be fieldable.
  *   - translation: An associative array of modules registered as field
  *     translation handlers. Array keys are the module names, array values
@@ -112,11 +117,11 @@ function hook_hook_info_alter(&$hooks) {
  *       omitted if this entity type exposes a single bundle (all entities have
  *       the same collection of fields). The name of this single bundle will be
  *       the same as the entity type.
- *     - label: The property name of the entity that contains the label. For
+ *     - label: The name of the property that contains the entity label. For
  *       example, if the entity's label is located in $entity->subject, then
- *       'subect' should be specified here. In case complex logic is required to
- *       build the label, a 'label callback' should be implemented instead. See
- *       entity_label() for details.
+ *       'subject' should be specified here. If complex logic is required to
+ *       build the label, a 'label callback' should be defined instead (see
+ *       the 'label callback' section above for details).
  *   - bundle keys: An array describing how the Field API can extract the
  *     information it needs from the bundle objects for this type (e.g
  *     $vocabulary objects for terms; not applicable for nodes). This entry can