Index: includes/actions.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/actions.inc,v
retrieving revision 1.32
diff -u -p -r1.32 actions.inc
--- includes/actions.inc	20 Sep 2009 07:47:44 -0000	1.32
+++ includes/actions.inc	9 Oct 2009 19:15:53 -0000
@@ -7,6 +7,25 @@
  */
 
 /**
+ * @defgroup actions Actions
+ * @{
+ * 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().
+ *
+ * @} End of "defgroup actions".
+ */
+
+/**
  * Performs a given list of actions by executing their callback functions.
  *
  * Given the IDs of actions to perform, this function finds out what the
Index: modules/comment/comment.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/comment/comment.module,v
retrieving revision 1.780
diff -u -p -r1.780 comment.module
--- modules/comment/comment.module	9 Oct 2009 17:05:52 -0000	1.780
+++ modules/comment/comment.module	9 Oct 2009 19:15:59 -0000
@@ -2295,9 +2295,17 @@ function vancode2int($c = '00') {
 
 /**
  * Implement hook_action_info().
+ *
+ * @ingroup actions
  */
 function comment_action_info() {
   return array(
+    'comment_publish_action' => array(
+      'label' => t('Publish comment'),
+      'type' => 'comment',
+      'configurable' => FALSE,
+      'triggers' => array('comment_insert', 'comment_update'),
+    ),
     'comment_unpublish_action' => array(
       'label' => t('Unpublish comment'),
       'type' => 'comment',
@@ -2309,17 +2317,45 @@ function comment_action_info() {
       'type' => 'comment',
       'configurable' => TRUE,
       'triggers' => array('comment_insert', 'comment_update'),
-    )
+    ),
   );
 }
 
 /**
- * Drupal action to unpublish a comment.
+ * Action to publish a comment.
  *
+ * @param $comment
+ *   An optional comment object.
  * @param $context
  *   Keyed array. Must contain the id of the comment if $comment is not passed.
+ *
+ * @ingroup actions
+ */
+function comment_publish_action($comment, $context = array()) {
+  if (isset($comment->cid)) {
+    $cid = $comment->cid;
+    $subject = $comment->subject;
+  }
+  else {
+    $cid = $context['cid'];
+    $subject = db_query('SELECT subject FROM {comment} WHERE cid = :cid', array(':cid', $cid))->fetchField();
+  }
+  db_update('comment')
+    ->fields(array('status' => COMMENT_PUBLISHED))
+    ->condition('cid', $cid)
+    ->execute();
+  watchdog('action', 'Published comment %subject.', array('%subject' => $subject));
+}
+
+/**
+ * Action to unpublish a comment.
+ *
  * @param $comment
  *   An optional comment object.
+ * @param $context
+ *   Keyed array. Must contain the id of the comment if $comment is not passed.
+ *
+ * @ingroup actions
  */
 function comment_unpublish_action($comment, $context = array()) {
   if (isset($comment->cid)) {
@@ -2338,9 +2374,38 @@ function comment_unpublish_action($comme
 }
 
 /**
+ * Action to unpublish a comment if it contains a certain string.
+ *
+ * @param $comment
+ *   A comment object.
+ * @param $context
+ *   An array providing more information about the context of the call to this action.
+ *   Unused here, since this action currently only supports the insert and update ops of
+ *   the comment hook, both of which provide a complete $comment object.
+ *
+ * @ingroup actions
+ * @see comment_unpublish_by_keyword_action_form()
+ * @see comment_unpublish_by_keyword_action_submit()
+ */
+function comment_unpublish_by_keyword_action($comment, $context) {
+  foreach ($context['keywords'] as $keyword) {
+    if (strpos($comment->comment, $keyword) !== FALSE || strpos($comment->subject, $keyword) !== FALSE) {
+      db_update('comment')
+        ->fields(array('status' => COMMENT_NOT_PUBLISHED))
+        ->condition('cid', $comment->cid)
+        ->execute();
+      watchdog('action', 'Unpublished comment %subject.', array('%subject' => $comment->subject));
+      break;
+    }
+  }
+}
+
+/**
  * Form builder; Prepare a form for blacklisted keywords.
  *
  * @ingroup forms
+ * @see comment_unpublish_by_keyword_action()
+ * @see comment_unpublish_by_keyword_action_submit()
  */
 function comment_unpublish_by_keyword_action_form($context) {
   $form['keywords'] = array(
@@ -2355,37 +2420,14 @@ function comment_unpublish_by_keyword_ac
 
 /**
  * Process comment_unpublish_by_keyword_action_form form submissions.
+ *
+ * @see comment_unpublish_by_keyword_action()
  */
 function comment_unpublish_by_keyword_action_submit($form, $form_state) {
   return array('keywords' => drupal_explode_tags($form_state['values']['keywords']));
 }
 
 /**
- * Implement a configurable Drupal action.
- *
- * Unpublish a comment if it contains a certain string.
- *
- * @param $context
- *   An array providing more information about the context of the call to this action.
- *   Unused here, since this action currently only supports the insert and update ops of
- *   the comment hook, both of which provide a complete $comment object.
- * @param $comment
- *   A comment object.
- */
-function comment_unpublish_by_keyword_action($comment, $context) {
-  foreach ($context['keywords'] as $keyword) {
-    if (strpos($comment->comment, $keyword) !== FALSE || strpos($comment->subject, $keyword) !== FALSE) {
-      db_update('comment')
-        ->fields(array('status' => COMMENT_NOT_PUBLISHED))
-        ->condition('cid', $comment->cid)
-        ->execute();
-      watchdog('action', 'Unpublished comment %subject.', array('%subject' => $comment->subject));
-      break;
-    }
-  }
-}
-
-/**
  * Implement hook_ranking().
  */
 function comment_ranking() {