Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Could do to explain that the flow is:
a) if there is a 'label callback', call that
b) if not, return the value of the key given as being the label
| Comment | File | Size | Author |
|---|---|---|---|
| #11 | 977346-11.patch | 3.67 KB | jhodgdon |
| #1 | 977346.drupal.entity_label-docs.patch | 692 bytes | joachim |
Comments
Comment #1
joachim CreditAttribution: joachim commentedPatch.
Comment #2
joachim CreditAttribution: joachim commentedI'm assuming the mention of hook_entity_info() will turn into a link in the generated API docs. If not, an @see is needed.
Comment #3
jhodgdonI'm not entirely sure it's necessary to document this (you can read the function)?
If you do want to document it, you might as well be a bit more specific. I dont' think "the entity's label as given by 'entity keys' is returned." really illuminates it (I still had to read the function to figure out what that line meant, and found out it was $info['entity keys']['label'] that was returned, which doesn't (to me) match what you wrote).
And yes, all functions turn into links if they have () after the function name.
Comment #4
joachim CreditAttribution: joachim commentedI'd like to not have to parse the code myself to figure out what it does...
But yes, wordiness :/
Basically, what I mean is this:
If there's a callback, that is called to provide the label. Otherwise, the entity's label is returned -- however, which entity property counts as the 'label' is itself defined back in $info['entity keys']['label']. (In other words, you have to specify which entity property is the label.)
Comment #5
jhodgdonHow about just adding a line saying
See hook_entity_info() for an explanation of how the label is determined.
Comment #6
jhodgdonJust as a note, I'd like not to have to document how labels work in more than one place, because it means we have to maintain the doc in more than one place, which is problematic.
Comment #7
joachim CreditAttribution: joachim commentedHmm... it's sending the user from a specialized function which can be relatively simply described to a monster -- it will take them ages to find the relevant bits in all that!
Also, it currently says:
...
Comment #8
jhodgdonWell let's improve the documentation on the hook then. Really, I don't want the documentation to be in two places. It's a rather complex piece of logic right now to generated the label (could be a function call or a text that's substituted and translated), and it could have hook_entity_info_alter() involved too, and who knows what other changes in the future.
Comment #9
joachim CreditAttribution: joachim commented> Really, I don't want the documentation to be in two places.
I can perfectly understand that.
But consider the use case I had: as a developer, I want to know what the entity_label function does. If I'm sent to hook_entity_info() then I have to wade through a huge page for the details I want. When I arrive on that page, I can't even see it might contain what I need.
Comment #10
jhodgdonI understand what you're saying too. My proposal is that we fix up the documentation of the hook so that it is clearer (I don't think it's good now), and that we point the user of entity_load() to specific elements of the hook_entity_load() return value doc ('label callback' and [entity keys][label] or whatever it is). Also, 'label callback' should refer to entity keys[label] if it doesn't already, and vice versa.
Comment #11
jhodgdonHere's a concrete proposal, in the form of a patch.
The common.inc part fixes up the doc for the entity_label() function, and the system.api.php part fixes up the 'label callback' and 'entity keys'['label'] sections of the hook_entity_info() doc.
Comment #12
joachim CreditAttribution: joachim commentedLooks great! :)
Comment #13
webchickCommitted to HEAD. Thanks!