From 5251e90c982b867d4bc25386b30f098f365cd52c Mon Sep 17 00:00:00 2001 From: webchick Date: Tue, 14 Feb 2012 13:44:23 -0500 Subject: Issue #1379126 by chris.leversuch, Albert Volkman, jhodgdon: Clean up API docs for trigger.module. --- modules/trigger/trigger.admin.inc | 28 ++++++++++++++++++---------- modules/trigger/trigger.module | 25 +++++++++++++++++++------ modules/trigger/trigger.test | 2 +- 3 files changed, 38 insertions(+), 17 deletions(-) (limited to 'modules/trigger') 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' -- cgit v1.2.3