Clarify $ops paramter options for hook_nodeapi()

Since this deals with API documentation, moving to the Drupal core queue.

It looks like D7 suffers from this as well, although the hooks have been renamed there to hook_node_update() and hook_node_insert().

This is D6 only. There is no hook_nodeapi in Drupal 7, as the individual "ops" from Drupal 6 were moved into their own hooks.

But the descriptions in 7.x for hook_node_insert/update also use present-tense, rather than past-tense, so if they're confusing in 6.x, they're confusing in 7.x as well. We just moved those hooks around slightly in 7.x.

Ran through the documentation in node.api.php in D7 and made certain descriptions/params past sense where it made sense.

This is an improvement, but I think we could do better still.

The thing I think that the documentation currently is doing a poor job of explaining is that the operations happen in the following order, one right after another.

From node_save:

  # call node-specific callback like poll_insert or poll_update.
  node_invoke($node, $op);

  # let field API work its magic [D7 only]
  $function = "field_attach_$op";
  $function('node', $node);

  # now let other modules have a crack.
  module_invoke_all('node_' . $op, $node);

So the thing to communicate is that hook_node_X (or hook_nodeapi op X) happens *directly* after the node is saved (and, in D7, its fields updated). The current wording I feel is a little too wishy-washy and implies that this happens at some point after but not immediately after. So maybe change instances of "A node has been saved" to "A node has 'just' been saved" or something? Not sure.
Also, I didn't do an exhaustive review, but something that caught my eye:

+++ modules/node/node.api.php	10 Aug 2009 18:20:30 -0000
@@ -187,7 +187,7 @@ function hook_node_access_records_alter(
- *   The operation being performed, 'view', 'update' or 'delete'.
+ *   The operation performed, 'view', 'update' or 'delete'.

Actually the old wording was correct. The operation is currently "being" performed. It's the things talking about the state of the node that need to be updated to past-tense.

21 days to code freeze. Better review yourself.

Marking http://drupal.org/node/332743 as a duplicate.
I think I filed something for this ages ago too.

Anyway, THANK YOU webchick!

Rerolled after applying change of wording suggested by webchick.

Not all of these make sense in past tense:

This review is powered by Dreditor.

+++ modules/node/node.api.php	11 Aug 2009 21:25:34 -0000
@@ -342,10 +342,10 @@ function hook_node_load($nodes, $types) 
- * The node is about to be shown on the add/edit form.
+ * The node has just been shown on the add/edit form.

This one should stay as it is, surely? It hasn't been shown to the user yet, as we are able to modify what the user will see.

+++ modules/node/node.api.php	11 Aug 2009 21:25:34 -0000
@@ -893,7 +893,7 @@ function hook_update($node) {
- *   The node to be validated.
+ *   The node that has just been validated.

It's still being validated, as we have the power to fail the validation here.

+++ modules/node/node.api.php	11 Aug 2009 21:25:34 -0000
@@ -923,7 +923,7 @@ function hook_validate($node, &$form) {
- *   The node to be displayed, as returned by node_load().
+ *   The node that has just been displayed, as returned by node_load().

It's not yet been displayed when we get here.

Beer-o-mania starts in 20 days! Don't drink and patch.

It looks like someone got to this during my absence and finished the patch. Good work to whomever completed it! This issue should probably now be closed as it looks to be fixed.

Let's fix this on 6 too, otherwise this will continue to cause confusion.

I just updated the update/insert ops on hook_nodeapi() in D6 also.