Index: modules/node/node.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/node/node.api.php,v
retrieving revision 1.1
diff -u -r1.1 node.api.php
--- modules/node/node.api.php	25 Nov 2008 02:37:32 -0000	1.1
+++ modules/node/node.api.php	4 Dec 2008 16:14:00 -0000
@@ -155,103 +155,233 @@
 }
 
 /**
- * Act on nodes defined by other modules.
+ * Fiter, substitute or otherwise alter the $node's raw text.
  *
- * Despite what its name might make you think, hook_nodeapi() is not
- * reserved for node modules. On the contrary, it allows modules to react
- * to actions affecting all kinds of nodes, regardless of whether that
- * module defined the node.
- *
- * It is common to find hook_nodeapi() used in conjunction with
- * hook_form_alter(). Modules use hook_form_alter() to place additional form
- * elements onto the node edit form, and hook_nodeapi() is used to read and
- * write those values to and from the database.
+ * The $node->content array has been rendered, so the node body or
+ * teaser is filtered and now contains HTML. This hook should only be 
+ * used when text substitution, filtering, or other raw text operations 
+ * are necessary.
+ * 
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_alter($node) {
+}
+
+/**
+ * Act on node deletion.
  *
- * @param &$node
+ * @param $node
+ *   The node that is being deleted.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_delete($node) {
+}
+
+/**
+ * A revision of the node is deleted.
+ *
+ * You can delete data associated with that revision.
+ *
+ * @param $node
  *   The node the action is being performed on.
- * @param $op
- *   What kind of action is being performed. Possible values:
- *   - "alter": the $node->content array has been rendered, so the node body or
- *     teaser is filtered and now contains HTML. This op should only be used when
- *     text substitution, filtering, or other raw text operations are necessary.
- *   - "delete": The node is being deleted.
- *   - "delete_revision": The revision of the node is deleted. You can delete data
- *     associated with that revision.
- *   - "insert": The node is being created (inserted in the database).
- *   - "load": The node is about to be loaded from the database. This hook
- *     can be used to load additional data at this time.
- *   - "prepare": The node is about to be shown on the add/edit form.
- *   - "prepare_translation": The node is being cloned for translation. Load
- *     additional data or copy values from $node->translation_source.
- *   - "print": Prepare a node view for printing. Used for printer-friendly
- *     view in book_module
- *   - "rss_item": An RSS feed is generated. The module can return properties
- *     to be added to the RSS item generated for this node. See comment_nodeapi()
- *     and upload_nodeapi() for examples. The $node passed can also be modified
- *     to add or remove contents to the feed item.
- *   - "search_result": The node is displayed as a search result. If you
- *     want to display extra information with the result, return it.
- *   - "presave": The node passed validation and is about to be saved. Modules may
- *      use this to make changes to the node before it is saved to the database.
- *   - "update": The node is being updated.
- *   - "update_index": The node is being indexed. If you want additional
- *     information to be indexed which is not already visible through
- *     nodeapi "view", then you should return it here.
- *   - "validate": The user has just finished editing the node and is
- *     trying to preview or submit it. This hook can be used to check
- *     the node data. Errors should be set with form_set_error().
- *   - "view": The node content is being assembled before rendering. The module
- *     may add elements $node->content prior to rendering. This hook will be
- *     called after hook_view().  The format of $node->content is the same as
- *     used by Forms API.
- * @param $a3
- *   - For "view", passes in the $teaser parameter from node_view().
- *   - For "validate", passes in the $form parameter from node_validate().
- * @param $a4
- *   - For "view", passes in the $page parameter from node_view().
- * @return
- *   This varies depending on the operation.
- *   - The "presave", "insert", "update", "delete", "print" and "view"
- *     operations have no return value.
- *   - The "load" operation should return an array containing pairs
- *     of fields => values to be merged into the node object.
- *
- * If you are writing a node module, do not use this hook to perform
- * actions on your type of node alone. Instead, use the hooks set aside
- * for node modules, such as hook_insert() and hook_form(). That said, for
- * some operations, such as "delete_revision" or "rss_item" there is no
- * corresponding hook so even the module defining the node will need to
- * implement hook_nodeapi().
+ * @return
+ *   None.
  */
-function hook_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {
-  switch ($op) {
-    case 'presave':
-      if ($node->nid && $node->moderate) {
-        // Reset votes when node is updated:
-        $node->score = 0;
-        $node->users = '';
-        $node->votes = 0;
-      }
-      break;
-    case 'insert':
-    case 'update':
-      if ($node->moderate && user_access('access submission queue')) {
-        drupal_set_message(t('The post is queued for approval'));
-      }
-      elseif ($node->moderate) {
-        drupal_set_message(t('The post is queued for approval. The editors will decide whether it should be published.'));
-      }
-      break;
-    case 'view':
-      $node->content['my_additional_field'] = array(
-        '#value' => theme('mymodule_my_additional_field', $additional_field),
-        '#weight' => 10,
-      );
-      break;
+function hook_nodeapi_delete_revision($node) {
+}
+
+/**
+ * The node being created (inserted in the database).
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_insert($node) {
+  if ($node->moderate && user_access('access submission queue')) {
+    drupal_set_message(t('The post is queued for approval'));
+  }
+  elseif ($node->moderate) {
+    drupal_set_message(t('The post is queued for approval. The editors will decide whether it should be published.'));
   }
 }
 
 /**
+ * The node is being loaded from the database.
+ *
+ * This hook can be used to load additional data at this time.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   An array containing pairs of fields => values to be merged into the node
+ *   object.
+ */
+function hook_nodeapi_load($node) {
+}
+
+/**
+ * The node is about to be shown on the add/edit form.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_prepare($node) {
+}
+
+/**
+ * The node is being cloned for translation.
+ *
+ * This hook can be used to load additional data or copy values from
+ * $node->translation_source.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_prepare_translation($node) {
+}
+
+/**
+ * Prepare a node view for printing.
+ *
+ * Used for printer-friendly view in book_module.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_print($node) {
+}
+
+/**
+ * An RSS feed is being generated.
+ *
+ * The module can return properties to be added to the RSS item generated for
+ * this node. See comment_nodeapi_rss_item() and upload_nodeapi_rss_item() for
+ * examples. The $node passed can also be modified to add or remove contents to
+ * the feed item.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   Extra information to be added to the RSS item.
+ */
+function hook_nodeapi_rss_item($node) {
+}
+
+/**
+ * The node is being displayed as a search result. 
+ *
+ * If you want to display extra information with the result, return it.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   Extra information to be displayed with search result.
+ */
+function hook_nodeapi_search_result($node) {
+}
+
+/**
+ * The node passed validation and is about to be saved.
+ *
+ * Modules may make changes to the node before it is saved to the database.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_presave($node) {
+  if ($node->nid && $node->moderate) {
+    // Reset votes when node is updated:
+    $node->score = 0;
+    $node->users = '';
+    $node->votes = 0;
+  }
+}
+
+/**
+ * The node being updated.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   None.
+ */
+function hook_nodeapi_update($node) {
+  if ($node->moderate && user_access('access submission queue')) {
+    drupal_set_message(t('The post is queued for approval'));
+  }
+  elseif ($node->moderate) {
+    drupal_set_message(t('The post is queued for approval. The editors will decide whether it should be published.'));
+  }
+}
+
+/**
+ * The node is being indexed.
+ *
+ * If you want additional information to be indexed which is not already
+ * visible through nodeapi "view", then you should return it here.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @return
+ *   Array of additional information to be indexed.
+ */
+function hook_nodeapi_update_index($node) {
+}
+
+/**
+ * The user has finished editing the node and is trying to preview or submit it. 
+ *
+ * This hook can be used to check the node data. Errors should be set with 
+ * form_set_error().
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @param $form
+ *   The $form parameter from node_validate().
+ * @return
+ *   None.
+ */
+function hook_nodeapi_validate($node, $form) {
+}
+
+/**
+ * The node content is being assembled before rendering. 
+ *
+ * The module may add elements $node->content prior to rendering. This hook 
+ * will be called after hook_view(). The format of $node->content is the 
+ * same as used by Forms API.
+ *
+ * @param $node
+ *   The node the action is being performed on.
+ * @param $teaser
+ *   The $teaser parameter from node_view().
+ * @param $page
+ *   The $page parameter from node_view().
+ * @return
+ *   None.
+ */
+function hook_nodeapi_view($node, $teaser, $page) {
+  $node->content['my_additional_field'] = array(
+    '#value' => theme('mymodule_my_additional_field', $additional_field),
+    '#weight' => 10,
+  );
+}
+
+/**
  * Define module-provided node types.
  *
  * This is a hook used by node modules. This hook is required for modules to