- Patch #721010 by jhodgdon: actions topic group needs more functions included...

- Patch #721010 by jhodgdon: actions topic group needs more functions included and better doc header.

includes/actions.inc

@@ -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:
+ * 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.
  *
- * \@ingroup actions
- * \@see comment_unpublish_by_keyword_action_form().
- * \@see comment_unpublish_by_keyword_action_submit().
+ * 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 can be passed into
+ *   actions_do() and will be passed along to the action function.
  *
  * @} 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.

modules/comment/comment.module

@@ -2360,8 +2360,6 @@ function vancode2int($c = '00') {
 
 /**
  * Implements hook_action_info().
- *
- * @ingroup actions
  */
 function comment_action_info() {
   return array(
@@ -2396,12 +2394,13 @@ function comment_action_info() {
 }
 
 /**
- * Action to publish a comment.
+ * 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 @@ function comment_publish_action($comment, $context = array()) {
 }
 
 /**
- * Action to unpublish a comment.
+ * 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 @@ function comment_unpublish_action($comment, $context = array()) {
 }
 
 /**
- * Action to unpublish a comment if it contains a certain string.
+ * Unpublishes a comment if it contains certain keywords.
  *
  * @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 @@ function comment_unpublish_by_keyword_action_submit($form, $form_state) {
 }
 
 /**
- * Action to save a comment.
+ * Saves a comment.
+ *
+ * @ingroup actions
  */
 function comment_save_action($comment) {
   comment_save($comment);

modules/node/node.module

@@ -3322,7 +3322,9 @@ function node_action_info() {
 }
 
 /**
- * Implements a Drupal action: sets the status of a node to 1 (published).
+ * Sets the status of a node to 1 (published).
+ *
+ * @ingroup actions
  */
 function node_publish_action($node, $context = array()) {
   $node->status = NODE_PUBLISHED;
@@ -3330,7 +3332,9 @@ function node_publish_action($node, $context = array()) {
 }
 
 /**
- * Implements a Drupal action: sets the status of a node to 0 (unpublished).
+ * Sets the status of a node to 0 (unpublished).
+ *
+ * @ingroup actions
  */
 function node_unpublish_action($node, $context = array()) {
   $node->status = NODE_NOT_PUBLISHED;
@@ -3338,7 +3342,9 @@ function node_unpublish_action($node, $context = array()) {
 }
 
 /**
- * Implements a Drupal action: sets sticky-at-top-of-list property to 1.
+ * 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;
@@ -3346,7 +3352,9 @@ function node_make_sticky_action($node, $context = array()) {
 }
 
 /**
- * Implements a Drupal action: sets sticky-at-top-of-list property to 0.
+ * 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;
@@ -3354,7 +3362,9 @@ function node_make_unsticky_action($node, $context = array()) {
 }
 
 /**
- * Implements a Drupal action: sets the promote property of a node to 1.
+ * Sets the promote property of a node to 1.
+ *
+ * @ingroup actions
  */
 function node_promote_action($node, $context = array()) {
   $node->promote = NODE_PROMOTED;
@@ -3362,7 +3372,9 @@ function node_promote_action($node, $context = array()) {
 }
 
 /**
- * Implements a Drupal action: sets the promote property of a node to 0.
+ * Sets the promote property of a node to 0.
+ *
+ * @ingroup actions
  */
 function node_unpromote_action($node, $context = array()) {
   $node->promote = NODE_NOT_PROMOTED;
@@ -3370,7 +3382,9 @@ function node_unpromote_action($node, $context = array()) {
 }
 
 /**
- * Implements a Drupal action: saves a node.
+ * Saves a node.
+ *
+ * @ingroup actions
  */
 function node_save_action($node) {
   node_save($node);
@@ -3378,7 +3392,15 @@ function node_save_action($node) {
 }
 
 /**
- * Implements a configurable Drupal action: assigns ownership of node to user.
+ * 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'];
@@ -3387,7 +3409,7 @@ function node_assign_owner_action($node, $context) {
 }
 
 /**
- * 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.');
@@ -3466,13 +3488,16 @@ function node_unpublish_by_keyword_action_submit($form, $form_state) {
 }
 
 /**
- * Implements a configurable Drupal action: unpublish node containing keywords.
+ * 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) {

modules/system/system.api.php

@@ -2690,6 +2690,8 @@ function hook_file_mimetype_mapping_alter(&$mapping) {
  *       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(

modules/system/system.module

@@ -2859,7 +2859,22 @@ function system_send_email_action_submit($form, $form_state) {
 }
 
 /**
- * Implements a configurable Drupal action: sends an email.
+ * 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'])) {
@@ -2909,7 +2924,19 @@ function system_message_action_submit($form, $form_state) {
 }
 
 /**
- * A configurable Drupal action. Sends a message to the current user's screen.
+ * 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'])) {
@@ -2921,7 +2948,7 @@ function system_message_action(&$entity, $context = array()) {
 }
 
 /**
- * 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(
@@ -2940,12 +2967,27 @@ function system_goto_action_submit($form, $form_state) {
   );
 }
 
+/**
+ * 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.
+ * Blocks the current user's IP address.
+ *
+ * @ingroup actions
  */
 function system_block_ip_action() {
   $ip = ip_address();

modules/user/user.module

@@ -3243,8 +3243,9 @@ function user_action_info() {
 }
 
 /**
- * Implement a Drupal action.
  * Blocks the current user.
+ *
+ * @ingroup actions
  */
 function user_block_user_action(&$entity, $context = array()) {
   if (isset($entity->uid)) {