Issue #1379126 by chris.leversuch, Albert Volkman, jhodgdon: Clean up API docs for trigger.module.

3 files changed, 38 insertions, 17 deletions

diff --git a/modules/trigger/trigger.admin.inc b/modules/trigger/trigger.admin.inc
index 7509eb35a..c91fd12c4 100644
--- a/modules/trigger/trigger.admin.inc
+++ b/modules/trigger/trigger.admin.inc
@@ -6,13 +6,16 @@
  */
 
 /**
- * Builds the form that allows users to assign actions to triggers.
+ * Builds a form that allows users to assign actions to triggers.
  *
  * @param $module_to_display
- *   Which tab of triggers to display. E.g., 'node' for all
- *   node-related triggers.
+ *   Which tab of triggers to display. E.g., 'node' for all node-related
+ *   triggers.
+ *
  * @return
  *   HTML form.
+ *
+ * @see trigger_menu()
  */
 function trigger_assign($module_to_display = NULL) {
   // If no type is specified we default to node actions, since they
@@ -36,16 +39,18 @@ function trigger_assign($module_to_display = NULL) {
 }
 
 /**
- * Confirm removal of an assigned action.
+ * Form constructor for confirmation page for removal of an assigned action.
  *
  * @param $module
  *   The tab of triggers the user will be directed to after successful
  *   removal of the action, or if the confirmation form is cancelled.
  * @param $hook
+ *   The name of the trigger hook, e.g., 'node_insert'.
  * @param $aid
  *   The action ID.
- * @ingroup forms
+ *
  * @see trigger_unassign_submit()
+ * @ingroup forms
  */
 function trigger_unassign($form, $form_state, $module, $hook = NULL, $aid = NULL) {
   if (!($hook && $aid)) {
@@ -79,7 +84,7 @@ function trigger_unassign($form, $form_state, $module, $hook = NULL, $aid = NULL
 }
 
 /**
- * Submit callback for trigger_unassign() form.
+ * Form submission handler for trigger_unassign().
  */
 function trigger_unassign_submit($form, &$form_state) {
   if ($form_state['values']['confirm'] == 1) {
@@ -108,9 +113,9 @@ function trigger_unassign_submit($form, &$form_state) {
  * @param $label
  *   A plain English description of what this trigger does.
  *
- * @ingoup forms
  * @see trigger_assign_form_validate()
  * @see trigger_assign_form_submit()
+ * @ingroup forms
  */
 function trigger_assign_form($form, $form_state, $module, $hook, $label) {
   $form['module'] = array(
@@ -197,9 +202,11 @@ function trigger_assign_form($form, $form_state, $module, $hook, $label) {
 }
 
 /**
- * Validation function for trigger_assign_form().
+ * Form validation handler for trigger_assign_form().
  *
  * Makes sure that the user is not re-assigning an action to an event.
+ *
+ * @see trigger_assign_form_submit()
  */
 function trigger_assign_form_validate($form, $form_state) {
   $form_values = $form_state['values'];
@@ -216,7 +223,9 @@ function trigger_assign_form_validate($form, $form_state) {
 }
 
 /**
- * Submit function for trigger_assign_form().
+ * Form submission handler for trigger_assign_form().
+ *
+ * @see trigger_assign_form_validate()
  */
 function trigger_assign_form_submit($form, &$form_state) {
   if (!empty($form_state['values']['aid'])) {
@@ -306,4 +315,3 @@ function theme_trigger_display($variables) {
   }
   return $output;
 }
-
diff --git a/modules/trigger/trigger.module b/modules/trigger/trigger.module
index 6c1f58ffa..55b64f09b 100644
--- a/modules/trigger/trigger.module
+++ b/modules/trigger/trigger.module
@@ -2,8 +2,7 @@
 
 /**
  * @file
- * Enables functions to be stored and executed at a later time when
- * triggered by other modules or by one of Drupal's core API hooks.
+ * Enables functions to be stored and executed at a later time.
  */
 
 /**
@@ -158,6 +157,7 @@ function trigger_trigger_info() {
  *
  * @param $hook
  *   The name of the hook being fired.
+ *
  * @return
  *   An array whose keys are action IDs that the user has associated with
  *   this trigger, and whose values are arrays containing the action type and
@@ -231,8 +231,8 @@ function _trigger_normalize_node_context($type, $node) {
  *
  * @param $node
  *   Node object.
- * @param $op
- *   Operation to trigger.
+ * @param $hook
+ *   Hook to trigger.
  * @param $a3
  *   Additional argument to action function.
  * @param $a4
@@ -384,8 +384,8 @@ function trigger_comment_view($comment) {
  *
  * @param $a1
  *   Comment object or array of form values.
- * @param $op
- *   Operation to trigger.
+ * @param $hook
+ *   Hook to trigger.
  */
 function _trigger_comment($a1, $hook) {
   // Keep objects for reuse so that changes actions make to objects can persist.
@@ -442,6 +442,7 @@ function trigger_cron() {
  *   The type of action that is about to be called.
  * @param $account
  *   The account object that was passed via the user hook.
+ *
  * @return
  *   The object expected by the action that is about to be called.
  */
@@ -518,6 +519,15 @@ function trigger_user_view($account) {
 
 /**
  * Calls action functions for user triggers.
+ *
+ * @param $hook
+ *   The hook that called this function.
+ * @param $edit
+ *   Edit variable passed in to the hook or empty array if not needed.
+ * @param $account
+ *   Account variable passed in to the hook.
+ * @param $method
+ *   Method variable passed in to the hook or NULL if not needed.
  */
 function _trigger_user($hook, &$edit, $account, $category = NULL) {
   // Keep objects for reuse so that changes actions make to objects can persist.
@@ -596,6 +606,9 @@ function trigger_actions_delete($aid) {
 
 /**
  * Retrieves and caches information from hook_trigger_info() implementations.
+ *
+ * @return
+ *   Array of all triggers.
  */
 function _trigger_get_all_info() {
   $triggers = &drupal_static(__FUNCTION__);
diff --git a/modules/trigger/trigger.test b/modules/trigger/trigger.test
index 9a9a4ba28..4a3016a7a 100644
--- a/modules/trigger/trigger.test
+++ b/modules/trigger/trigger.test
@@ -11,7 +11,7 @@
 class TriggerWebTestCase extends DrupalWebTestCase {
 
   /**
-   * Configure an advanced action.
+   * Configures an advanced action.
    *
    * @param $action
    *   The name of the action callback. For example: 'user_block_user_action'