Documentation problem with hook_load

Whoops, sorry for the double line at the end there...hmm, looks like previewing left some artifacts in my post, sorry about that, I'll be more careful in future postings.

I see where you are confused (my fault), let me rephrase:

Based on http://php.net/manual/en/language.oop5.references.php (link provided by fangel http://api.drupal.org/api/drupal/modules--node--node.api.php/function/ho...), $nodes is keyed by nid, but each of the array members contain transparent references (pointers/aliases?) to the node objects in memory, rather than copies of the objects themselves (which would normally be the case, except when it comes to objects).

This fact makes the code example somewhat misleading (although not incorrect). The array members in $nodes can be modified as if they were copies of the object, but the affected objects are actually considered global to this particular function (due to the reference/alias/pointer), thereby making a return statement unnecessary.

Without &$nodes in the signature, and no return statement, less savvy programmers such as myself assume a local copy of all items in $nodes, and then scratch our heads at the lack of a return statement (which was required in hook_load for D6, adding to the confusion).

I think adding a line or two of documentation here stating that a return statement is no longer necessary and that $nodes is actually a bunch of references (or whatever the proper terminology is) would be quite helpful to less experienced programmers such as myself. Based on the comments for hook_node_load, I'm not the first to be confused about this issue (or maybe I was, but I am not the only one :-D).

I'll leave the 'fix' up to you, although I can roll a patch if requested.

Since the current documentation is technically correct, I'm fine with closing this ticket as-is, and simply add comments to each of the functions to clear the confusion.