hook_prepare() example is not useful

What is the "Newbie" tag? I'm not familiar with this. If you mean "A new contributor could patch this", then the correct tag is "Novice". If you mean "I'm a newbie and I need this information", then the correct tag is "DX (Developer Experience)". I'm assuming the latter... but this is just a regular documentation issue with some hook documentation, so I think it doesn't need a special DX tag, since that is for more pervasive issues.

Anyway, thanks for the issue! Patch welcome...

As stated, "come up with a better example and completely rewrite the body of the function", without any further guidance, is probably not a great "Novice" issue... Any thoughts on what a better example would be?

If we take the example from one of the existing implementations there are two likely candidates: comment_node_prepare() and book_node_prepare(). Both functions deal with setting of additional node properties that are required by the respective modules. Comment's is the simpler of the two, only setting the one parameter indicating whether comments are open/closed. Book's is more involved, dealing with all the stuff relating to the book hierarchies. It may be a little complex, but may have some additional benefit because it demonstrates checking permissions before adding the properties.

I don't know if it's customary to take the API examples from existing implementations, but I know that there are a lot of places in core where that was done in the past.

Yes -- then let's take it from Comment.

Now it's probably a good Novice task. Thanks!

Uploaded the patch. Please review now.

Actually, sorry, no... the above information was not good.

This is talking about hook_prepare(), which is only invoked on the module that defines the node type. So for instance, book_prepare() would be invoked for book nodes. comment_node_prepare() is actually an implementation of hook_node_prepare(), not hook_prepare().

So we'll have to figure out a better function body to put in this hook.

Probably it should just be something simple, like adding a new field value to the node object. How about something like:

// Set a value that would be used in hook_form().
$node->mymodule_value = 'foo';

Oh no. I'm sorry. =( The list of implementations on hook_prepare()'s API page mistakenly includes all of the hook_node_prepare() implementations. I didn't even notice the problem.

Yes, see the note above that list "generated by pattern matching"... that's just how it is.

Yes and in this case it was misleading. That list is generated through pattern matching, and it finds all functions that end in _prepare, so it found a bunch of functions, none of which is actually an implementation of hook_prepare. See previous comments...

@jhodgdon, Something like this ?

function hook_node_prepare($node) {
  if (!isset($node->mymodule)) {
    $node->mymodule_value = 'foo';
  }
}
 

Yes, that looks fine, although in the issset line it should be $node->mymodule_value presumably?

Here is a patch.

I believe it automatic test fail because of :

function hook_node_prepare($node) { and phpstorm it was also complaining about it.

I change it to this now:

function hook_prepare($node) {
  if (!isset($node->mymodule_value)) {
    $node->mymodule_value = 'foo';
  }
}

Here is new patch.

This looks fine to me. Thanks!

Committed to 7.x - thanks!