Document that the hook_entity_load() and hook_ENTITY_TYPE_load() functions should never have their own static caches

Seems like a good novice task.

tagging

It's a good way to start contributing to core... I'm on it...

Thanks lnunesbr! The first step is to assign the issue to yourself (using the "Assigned" field above the new comment form).

Hi,

Is anyone working on this issue? If not, I'm happy to take the ball on this.

aLearner: Apparently not. Please assign it to yourself. :)

jhodgdon,

Roger that.

Also, any pointers on how I should go about identifying the files that need to be documented with the change? I'm not a grep guru. I haven't been able to figure out how to get Eclipse working with Drupal either. A nudge in the right direction would be greatly appreciated!

See http://drupal.org/node/144223 for information on how to update API docs in general (and how to figure out where the files are).
See http://drupal.org/novice if you need help with the git/patching process.

jhodgdon,

Thank you for the pointers. I'm waiting for my patch to be reviewed and thought I could help with documentation (since this is an area that's also new to me (along with everything else)) in the interim.

I'll go through both links carefully. The second one I've seen before - the first one I haven't seen at all.

Excellent! You might also be interested in http://drupal.org/core-office-hours

jhodgdon,

Thank you. Yes, I'm aware of office hours and have been attending them.

There's no patch here, so this issue is still "active".

jhodgdon,

OK. Cool. Thanks for fixing this.

Here's the result of a search for 'function hook_*_load(' from the /core/modules directory in Drupal 8.

The ##: represents the line number of the file where the function was found.

/core/modules/comment
comment.api.php
54: function hook_comment_load($comments) { 

/core/modules/entity
entity.api.php
227: function hook_entity_load($entities, $type) { 

/core/modules/field
field.api.php (4 matches)
313: function hook_field_load($entity_type, $entities, $field, $instances, $langcode, &$items, $age) { 

/core/modules/node
node.api.php
544: function hook_node_load($nodes, $types) { 

/core/modules/system
system.api.php
2,202: function hook_file_load($files) { 

/core/modules/taxonomy
taxonomy.api.php (2 matches)
22: function hook_taxonomy_vocabulary_load($vocabularies) { 
103: function hook_taxonomy_term_load($terms) { 

/core/modules/user
user.api.php
26: function hook_user_load($users) { 

jthorson,

Thank you for furnishing this report. It's very helpful. Thanks again.

OK. So I looked at the comments for the following function

/core/modules/comment
comment.api.php
54: function hook_comment_load($comments) {

They read

/**
 * Act on comments being loaded from the database.
 *
 * @param $comments
 *  An array of comment objects indexed by cid.
 */

I was wondering what I need to change them to, after reading Dave Reid's comments, since what's expressed as part of the solution is not clear to me. Would something like this, for example, be acceptable?

/**
 * Act on comments being loaded from the database.
 * 
 * Note: The 'hook_comment_load function' should always be treated as 'fresh' and never statically cache 
 * it's data. The only time this hook will get invoked is 
 * (1) if '$reset' is 'TRUE' or 
 * (2) a new entity that hasn't been seen or retrieved yet is loaded.  
 *
 * @param $comments
 *  An array of comment objects indexed by cid.
 */

Something *like* that, yes... Let's see if we can write it a little better and follow documentation standards though. :) Things that I noticed:
- "it's" should be "its"
- I think it goes past 80-character lines
- Doesn't use list formatting -- actually I think we shouldn't even use a list here.
- Refers to $reset, which isn't a parameter to this function. It needs to say something more like "This hook will only be invoked from whatever_function() if its $reset argument is TRUE, or if new comments that haven't been retrieved yet are requested."... and you'd need to figure out what whatever_function() is.
- I don't really like the "treated as 'fresh'" terminology because I don't know what it means.
- Don't put 'hook_comment_load' function in quotes. Actually it should say something like "Functions that implement this hook should ...".

Documentation standards for reference:
http://drupal.org/node/1354

jhodgdon,

Thank you for taking the time to go through my post and get back to me with your suggestion. I really appreciate it.

[1] "it's" should be "its"

Right. Sorry about that.

[2] I think it goes past 80-character lines

OK.

[3] Doesn't use list formatting -- actually I think we shouldn't even use a list here.

Understood.

[4] Refers to $reset, which isn't a parameter to this function. It needs to say something more like "This hook will only be invoked from whatever_function() if its $reset argument is TRUE, or if new comments that haven't been retrieved yet are requested."... and you'd need to figure out what whatever_function() is.

(a) And how would I figure out what 'whatever_function' is?

(b) Also, do you mean

'...or if new contents that haven't been retrieved yet are requested...'

[5] I don't really like the "treated as 'fresh'" terminology because I don't know what it means.

Neither do I, actually. I took the terminology straight from the original poster. Things would be easier for me to comment if I understood what it is I'm trying to comment. This is not clear to me. Any help on this front would be greatly appreciated.

[6] Don't put 'hook_comment_load' function in quotes. Actually it should say something like "Functions that implement this hook should ...".

All right.

Thank you for the reference to the documentation link. I'll certainly go through.

Thanks again.

OK, removing the Novice tag.... aLearner: feel free to pursue this, but I'm realizing it is a bit more involved than the average Novice-tagged issue. It will require whoever takes this issue on to learn about what these hooks do and how they are invoked, in order to write good documentation for this.

Regarding the "whatever" functions... What's needed here is that for each of these hooks, someone needs to figure out when they are invoked, which is usually within a function named entity_load(), entity_load_multiple(), node_load(), comment_load(), etc. Some of these hooks may be invoked from more than one function. And the idea is that if those functions have a $reset=TRUE argument, then the hook will be invoked, and otherwise those functions are using a cache and the previously-loaded versions of the node, comment, etc. will be loaded.

Somehow, in some readable format, this information needs to get into the documentation of the hooks listed in comment #15 above. I think that the text added to each hook should be specific to each hook. So for instance in hook_comment_load(), it should refer to comments, and in hook_node_load(), it should refer to nodes.

jhodgdon,

Thank you for your detailed reply. I'll certainly try to do this if you think a total novice like me can indeed do it. Perhaps it'll be a great learning opportunity to dig deep and find out what the hooks do and how they are invoked? Admittedly, I don't know anything at this point but I'm very eager to learn and to contribute.

Thanks also for the detailed explanation on the 'whatever' functions.

What do you think would be a good, next step, then?

You'll probably need to get some help/orientation at Core Office Hours as a next step.

This is not moving forward since maybe I'm just too novice to take this on (despite being present during office hours). I'm going ahead and unassigning myself this so that perhaps someone that has the knowledge / experience can perhaps push things forward.

At this point, I do not think this is an issue any more. The Drupal 8 cache system has changed radically, and people should be using cache tags etc. if they are developing with the cache system. So, moving this to Drupal 7.