Index: modules/comment/comment.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/comment/comment.module,v
retrieving revision 1.846
diff -u -r1.846 comment.module
--- modules/comment/comment.module	22 Feb 2010 15:38:52 -0000	1.846
+++ modules/comment/comment.module	24 Feb 2010 02:28:44 -0000
@@ -2360,8 +2360,6 @@
 
 /**
  * Implements hook_action_info().
- *
- * @ingroup actions
  */
 function comment_action_info() {
   return array(
@@ -2396,12 +2394,13 @@
 }
 
 /**
- * Action to publish a comment.
+ * Action function: Publishes a comment.
  *
  * @param $comment
  *   An optional comment object.
- * @param $context
- *   Keyed array. Must contain the id of the comment if $comment is not passed.
+ * @param array $context
+ *   Array with components:
+ *   - 'cid': Comment ID. Required if $comment is not given.
  *
  * @ingroup actions
  */
@@ -2422,12 +2421,13 @@
 }
 
 /**
- * Action to unpublish a comment.
+ * Action function: Unpublishes a comment.
  *
  * @param $comment
  *   An optional comment object.
- * @param $context
- *   Keyed array. Must contain the id of the comment if $comment is not passed.
+ * @param array $context
+ *   Array with components:
+ *   - 'cid': Comment ID. Required if $comment is not given.
  *
  * @ingroup actions
  */
@@ -2448,12 +2448,14 @@
 }
 
 /**
- * Action to unpublish a comment if it contains a certain string.
+ * Action function: Unpublishes a comment if it contains a certain string.
  *
  * @param $comment
- *   A comment object.
- * @param $context
- *   Keyed array. Must contain the id of the comment if $comment is not passed.
+ *   Comment object to modify.
+ * @param array $context
+ *   Array with components:
+ *   - 'keywords': Keywords to look for. If the comment contains at least one
+ *     of the keywords, it is unpublished.
  *
  * @ingroup actions
  * @see comment_unpublish_by_keyword_action_form()
@@ -2498,7 +2500,9 @@
 }
 
 /**
- * Action to save a comment.
+ * Action function: Saves a comment.
+ *
+ * @ingroup actions
  */
 function comment_save_action($comment) {
   comment_save($comment);
Index: modules/user/user.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.module,v
retrieving revision 1.1127
diff -u -r1.1127 user.module
--- modules/user/user.module	22 Feb 2010 19:51:15 -0000	1.1127
+++ modules/user/user.module	24 Feb 2010 02:28:46 -0000
@@ -3243,8 +3243,9 @@
 }
 
 /**
- * Implement a Drupal action.
- * Blocks the current user.
+ * Action function: Blocks the current user.
+ *
+ * @ingroup actions
  */
 function user_block_user_action(&$entity, $context = array()) {
   if (isset($entity->uid)) {
Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.136
diff -u -r1.136 system.api.php
--- modules/system/system.api.php	23 Feb 2010 05:04:50 -0000	1.136
+++ modules/system/system.api.php	24 Feb 2010 02:28:45 -0000
@@ -2690,6 +2690,8 @@
  *       Modules that are processing actions (like Trigger module) should take
  *       special care for the "presave" hook, in which case a dependent "save"
  *       action should NOT be invoked.
+ *
+ * @ingroup actions
  */
 function hook_action_info() {
   return array(
Index: modules/system/system.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.module,v
retrieving revision 1.890
diff -u -r1.890 system.module
--- modules/system/system.module	17 Feb 2010 09:09:30 -0000	1.890
+++ modules/system/system.module	24 Feb 2010 02:28:45 -0000
@@ -2853,7 +2853,22 @@
 }
 
 /**
- * Implements a configurable Drupal action: sends an email.
+ * Action function: Sends an e-mail message.
+ *
+ * @param object $entity
+ *   An optional node object, which will be added as $context['node'] if
+ *   provided.
+ * @param array $context
+ *   Array with the following elements:
+ *   - 'recipient': E-mail message recipient. This will be passed through
+ *     token_replace().
+ *   - 'subject': The subject of the message. This will be passed through
+ *     token_replace().
+ *   - 'message': The message to send. This will be passed through
+ *     token_replace().
+ *   - Other elements will be used as the data for token replacement.
+ *
+ * @ingroup actions
  */
 function system_send_email_action($entity, $context) {
   if (empty($context['node'])) {
@@ -2903,7 +2918,19 @@
 }
 
 /**
- * A configurable Drupal action. Sends a message to the current user's screen.
+ * Action function: Sends a message to the current user's screen.
+ *
+ * @param object $entity
+ *   An optional node object, which will be added as $context['node'] if
+ *   provided.
+ * @param array $context
+ *   Array with the following elements:
+ *   - 'message': The message to send. This will be passed through
+ *     token_replace().
+ *   - Other elements will be used as the data for token replacement in
+ *     the message.
+ *
+ * @ingroup actions
  */
 function system_message_action(&$entity, $context = array()) {
   if (empty($context['node'])) {
@@ -2915,7 +2942,7 @@
 }
 
 /**
- * Implements a configurable Drupal action: redirect user to a URL.
+ * Settings form for system_goto_action().
  */
 function system_goto_action_form($context) {
   $form['url'] = array(
@@ -2934,12 +2961,27 @@
   );
 }
 
+/**
+ * Action function: Redirects to a different URL.
+ *
+ * @param $entity
+ *   Ignored.
+ * @param array $context
+ *   Array with the following elements:
+ *   - 'url': URL to redirect to.  This will be passed through
+ *     token_replace().
+ *   - Other elements will be used as the data for token replacement.
+ *
+ * @ingroup actions
+ */
 function system_goto_action($entity, $context) {
   drupal_goto(token_replace($context['url'], $context));
 }
 
 /**
- * Implements a Drupal action: blocks the user's IP address.
+ * Action function: Blocks the current user's IP address.
+ *
+ * @ingroup actions
  */
 function system_block_ip_action() {
   $ip = ip_address();
Index: modules/node/node.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/node/node.module,v
retrieving revision 1.1234
diff -u -r1.1234 node.module
--- modules/node/node.module	23 Feb 2010 05:03:38 -0000	1.1234
+++ modules/node/node.module	24 Feb 2010 02:28:45 -0000
@@ -3330,7 +3330,9 @@
 }
 
 /**
- * Implements a Drupal action: sets the status of a node to 1 (published).
+ * Action function: Sets the status of a node to 1 (published).
+ *
+ * @ingroup actions
  */
 function node_publish_action($node, $context = array()) {
   $node->status = NODE_PUBLISHED;
@@ -3338,7 +3340,9 @@
 }
 
 /**
- * Implements a Drupal action: sets the status of a node to 0 (unpublished).
+ * Action function: Sets the status of a node to 0 (unpublished).
+ *
+ * @ingroup actions
  */
 function node_unpublish_action($node, $context = array()) {
   $node->status = NODE_NOT_PUBLISHED;
@@ -3346,7 +3350,9 @@
 }
 
 /**
- * Implements a Drupal action: sets sticky-at-top-of-list property to 1.
+ * Action function: Sets the sticky-at-top-of-list property of a node to 1.
+ *
+ * @ingroup actions
  */
 function node_make_sticky_action($node, $context = array()) {
   $node->sticky = NODE_STICKY;
@@ -3354,7 +3360,9 @@
 }
 
 /**
- * Implements a Drupal action: sets sticky-at-top-of-list property to 0.
+ * Action function: Sets the sticky-at-top-of-list property of a node to 0.
+ *
+ * @ingroup actions
  */
 function node_make_unsticky_action($node, $context = array()) {
   $node->sticky = NODE_NOT_STICKY;
@@ -3362,7 +3370,9 @@
 }
 
 /**
- * Implements a Drupal action: sets the promote property of a node to 1.
+ * Action function: Sets the promote property of a node to 1.
+ *
+ * @ingroup actions
  */
 function node_promote_action($node, $context = array()) {
   $node->promote = NODE_PROMOTED;
@@ -3370,7 +3380,9 @@
 }
 
 /**
- * Implements a Drupal action: sets the promote property of a node to 0.
+ * Action function: Sets the promote property of a node to 0.
+ *
+ * @ingroup actions
  */
 function node_unpromote_action($node, $context = array()) {
   $node->promote = NODE_NOT_PROMOTED;
@@ -3378,7 +3390,9 @@
 }
 
 /**
- * Implements a Drupal action: saves a node.
+ * Action function: Saves a node.
+ *
+ * @ingroup actions
  */
 function node_save_action($node) {
   node_save($node);
@@ -3386,7 +3400,15 @@
 }
 
 /**
- * Implements a configurable Drupal action: assigns ownership of node to user.
+ * Action function: Assigns ownership of a node to a user.
+ *
+ * @param $node
+ *   A node object to modify.
+ * @param $context
+ *   Array with the following elements:
+ *   - 'owner_uid': User ID to assign to the node.
+ *
+ * @ingroup actions
  */
 function node_assign_owner_action($node, $context) {
   $node->uid = $context['owner_uid'];
@@ -3395,7 +3417,7 @@
 }
 
 /**
- * Generates settings form for node_assign_owner_action().
+ * Generates the settings form for node_assign_owner_action().
  */
 function node_assign_owner_action_form($context) {
   $description = t('The username of the user to which you would like to assign ownership.');
@@ -3474,13 +3496,16 @@
 }
 
 /**
- * Implements a configurable Drupal action: unpublish node containing keywords.
+ * Action function: Unpublishes a node containing certain keywords.
  *
  * @param $node
- *   A node object.
+ *   A node object to modify.
  * @param $context
- *   An array providing more information about the context of the call to this
- *   action.
+ *   Array with the following elements:
+ *   - 'keywords': Array of keywords. If any keyword is present in the rendered
+ *     node, the node's status flag is set to unpublished.
+ *
+ * @ingroup actions
  */
 function node_unpublish_by_keyword_action($node, $context) {
   foreach ($context['keywords'] as $keyword) {
Index: includes/actions.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/actions.inc,v
retrieving revision 1.34
diff -u -r1.34 actions.inc
--- includes/actions.inc	18 Oct 2009 06:56:23 -0000	1.34
+++ includes/actions.inc	24 Feb 2010 02:28:44 -0000
@@ -11,16 +11,17 @@
  * @{
  * Functions that perform an action on a certain system object.
  *
- * All modules should declare their action functions to be in this group and
- * each action function should reference its configuration form, validate, and
- * submit functions using \@see. Conversely, form, validate, and submit
- * functions should reference the action function using \@see. For examples of
- * this see comment_unpublish_by_keyword_action(), which has the following in
- * its doxygen documentation:
- *
- * \@ingroup actions
- * \@see comment_unpublish_by_keyword_action_form().
- * \@see comment_unpublish_by_keyword_action_submit().
+ * Action functions are declared by modules by implementing hook_action_info().
+ * Modules can cause action functions to run by calling actions_do(), and
+ * trigger.module provides a user interface that lets administrators define
+ * events that cause action functions to run.
+ *
+ * Each action function takes two to four arguments:
+ * - $entity: The object that the action acts on, such as a node, comment, or
+ *   user.
+ * - $context: Array of additional information about what triggered the action.
+ * - $a1, $a2: Optional additional information, which must be passed into
+ *   actions_do().
  *
  * @} End of "defgroup actions".
  */
@@ -51,6 +52,8 @@
  * @return
  *   An associative array containing the results of the functions that
  *   perform the actions, keyed on action ID.
+ *
+ * @ingroup actions
  */
 function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a2 = NULL) {
   // $stack tracks the number of recursive calls.