1 files changed, 44 insertions, 23 deletions
diff --git a/modules/node/node.api.php b/modules/node/node.api.php
index 6d14a0737..052effc9b 100644
--- a/modules/node/node.api.php
+++ b/modules/node/node.api.php
@@ -498,9 +498,18 @@ function hook_node_revision_delete($node) {
 /**
  * Respond to creation of a new node.
  *
- * This hook is invoked from node_save() after the node is inserted into the
- * node table in the database, after the type-specific hook_insert() is invoked,
- * and after field_attach_insert() is called.
+ * This hook is invoked from node_save() after the database query that will
+ * insert the node into the node table is scheduled for execution, after the
+ * type-specific hook_insert() is invoked, and after field_attach_insert() is
+ * called.
+ *
+ * Note that when this hook is invoked, the changes have not yet been written to
+ * the database, because a database transaction is still in progress. The
+ * transaction is not finalized until the save operation is entirely completed
+ * and node_save() goes out of scope. You should not rely on data in the
+ * database at this time as it is not updated yet. You should also note that any
+ * write/update database queries executed from this hook are also not committed
+ * immediately. Check node_save() and db_transaction() for more info.
  *
  * @param $node
  *   The node that is being created.
@@ -517,40 +526,43 @@ function hook_node_insert($node) {
 }
 
 /**
- * Act on nodes being loaded from the database.
+ * Act on arbitrary nodes being loaded from the database.
+ *
+ * This hook should be used to add information that is not in the node or
+ * node revisions table, not to replace information that is in these tables
+ * (which could interfere with the entity cache). For performance reasons,
+ * information for all available nodes should be loaded in a single query where
+ * possible.
  *
  * This hook is invoked during node loading, which is handled by entity_load(),
  * via classes NodeController and DrupalDefaultEntityController. After the node
  * information is read from the database or the entity cache, hook_load() is
- * invoked on the node's content type module, then field_attach_node_revision()
+ * invoked on the node's content type module, then field_attach_load_revision()
  * or field_attach_load() is called, then hook_entity_load() is invoked on all
  * implementing modules, and finally hook_node_load() is invoked on all
  * implementing modules.
  *
- * This hook should only be used to add information that is not in the node or
- * node revisions table, not to replace information that is in these tables
- * (which could interfere with the entity cache). For performance reasons,
- * information for all available nodes should be loaded in a single query where
- * possible.
- *
- * The $types parameter allows for your module to have an early return (for
- * efficiency) if your module only supports certain node types. However, if your
- * module defines a content type, you can use hook_load() to respond to loading
- * of just that content type.
- *
  * @param $nodes
  *   An array of the nodes being loaded, keyed by nid.
  * @param $types
- *   An array containing the types of the nodes.
+ *   An array containing the node types present in $nodes. Allows for an early
+ *   return for modules that only support certain node types. However, if your
+ *   module defines a content type, you can use hook_load() to respond to
+ *   loading of just that content type.
  *
  * For a detailed usage example, see nodeapi_example.module.
  *
  * @ingroup node_api_hooks
  */
 function hook_node_load($nodes, $types) {
-  $result = db_query('SELECT nid, foo FROM {mytable} WHERE nid IN(:nids)', array(':nids' => array_keys($nodes)));
-  foreach ($result as $record) {
-    $nodes[$record->nid]->foo = $record->foo;
+  // Decide whether any of $types are relevant to our purposes.
+  if (count(array_intersect($types_we_want_to_process, $types))) {
+    // Gather our extra data for each of these nodes.
+    $result = db_query('SELECT nid, foo FROM {mytable} WHERE nid IN(:nids)', array(':nids' => array_keys($nodes)));
+    // Add our extra data to the node objects.
+    foreach ($result as $record) {
+      $nodes[$record->nid]->foo = $record->foo;
+    }
   }
 }
 
@@ -684,9 +696,18 @@ function hook_node_presave($node) {
 /**
  * Respond to updates to a node.
  *
- * This hook is invoked from node_save() after the node is updated in the node
- * table in the database, after the type-specific hook_update() is invoked, and
- * after field_attach_update() is called.
+ * This hook is invoked from node_save() after the database query that will
+ * update node in the node table is scheduled for execution, after the
+ * type-specific hook_update() is invoked, and after field_attach_update() is
+ * called.
+ *
+ * Note that when this hook is invoked, the changes have not yet been written to
+ * the database, because a database transaction is still in progress. The
+ * transaction is not finalized until the save operation is entirely completed
+ * and node_save() goes out of scope. You should not rely on data in the
+ * database at this time as it is not updated yet. You should also note that any
+ * write/update database queries executed from this hook are also not committed
+ * immediately. Check node_save() and db_transaction() for more info.
  *
  * @param $node
  *   The node that is being updated.