From 283bb10c3597c6cf5ada14503b77c03cd4d24bc3 Mon Sep 17 00:00:00 2001 From: Rouslan Placella Date: Fri, 8 Jul 2011 16:36:20 +0100 Subject: [PATCH] More comments for functions that handle Routines, Triggers and Events --- libraries/rte/rte_events.lib.php | 34 ++++++++++++++++++++++++++---- libraries/rte/rte_list.lib.php | 14 ++++++------ libraries/rte/rte_routines.lib.php | 33 +++++++++++++++++++++-------- libraries/rte/rte_triggers.lib.php | 34 ++++++++++++++++++++++++++---- 4 files changed, 91 insertions(+), 24 deletions(-) diff --git a/libraries/rte/rte_events.lib.php b/libraries/rte/rte_events.lib.php index 07a6e0d96f..5bdd02ae0b 100644 --- a/libraries/rte/rte_events.lib.php +++ b/libraries/rte/rte_events.lib.php @@ -7,6 +7,15 @@ if (! defined('PHPMYADMIN')) { exit; } +/** + * This function is defined in: rte_routines.lib.php, rte_triggers.lib.php and + * rte_events.lib.php. It is used to retreive some language strings that are + * used in functionalities that are common to routines, triggers and events. + * + * @param string $index The index of the string to get + * + * @return string The requested string or an empty string, if not available + */ function PMA_RTE_getWord($index) { $words = array( @@ -20,7 +29,7 @@ function PMA_RTE_getWord($index) 'title' => __('Events'), ); return isset($words[$index]) ? $words[$index] : ''; -} +} // end PMA_RTE_getWord() /** * Main function for the events functionality @@ -49,6 +58,9 @@ function PMA_RTE_main() echo PMA_EVN_getFooterLinks(); } // end PMA_RTE_main() +/** + * Handles editor requests for adding or editing an item + */ function PMA_EVN_handleEditor() { global $_REQUEST, $_POST, $errors, $db, $table; @@ -184,10 +196,10 @@ function PMA_EVN_handleEditor() } } } -} +} // end PMA_EVN_handleEditor() /** - * This function will generate the values that are required to for the ditor + * This function will generate the values that are required to for the editor * * @return array Data necessary to create the editor. */ @@ -264,6 +276,20 @@ function PMA_EVN_getDataFromName($name) return $retval; } // end PMA_EVN_getDataFromName() +/** + * Displays a form used to add/edit an event + * + * @param string $mode If the editor will be used edit an event + * or add a new one: 'edit' or 'add'. + * @param string $operation If the editor was previously invoked with + * JS turned off, this will hold the name of + * the current operation + * @param array $item Data for the event returned by + * PMA_EVN_getDataFromRequest() or + * PMA_EVN_getDataFromName() + * + * @return string HTML code for the editor. + */ function PMA_EVN_getEditorForm($mode, $operation, $item) { global $db, $table, $titles, $event_status, $event_type, $event_interval; @@ -421,7 +447,7 @@ function PMA_EVN_getEditorForm($mode, $operation, $item) $retval .= "\n\n"; return $retval; -} +} // end PMA_EVN_getEditorForm() /** * Composes the query necessary to create an event from an HTTP request. diff --git a/libraries/rte/rte_list.lib.php b/libraries/rte/rte_list.lib.php index 862863c7be..f2ea60d0eb 100644 --- a/libraries/rte/rte_list.lib.php +++ b/libraries/rte/rte_list.lib.php @@ -95,7 +95,7 @@ function PMA_RTE_getList($type, $items) } // end PMA_RTE_getList() /** - * Creates the contents for a cell in the list of routines + * Creates the contents for a row in the list of routines * * @param array $routine An array of routine data * @param string $rowclass Empty or one of ['even'|'odd'] @@ -181,10 +181,10 @@ function PMA_RTN_getRowForList($routine, $rowclass = '') } // end PMA_RTN_getRowForList() /** - * Creates the contents for a cell in the list of triggers + * Creates the contents for a row in the list of triggers * - * @param string $field What kind of cell to return - * @param array $trigger An array of trigger data + * @param array $routine An array of routine data + * @param string $rowclass Empty or one of ['even'|'odd'] * * @return string HTML code of a cell for the list of triggers */ @@ -239,10 +239,10 @@ function PMA_TRI_getRowForList($trigger, $rowclass = '') } // end PMA_TRI_getRowForList() /** - * Creates the contents for a cell in the list of events + * Creates the contents for a row in the list of events * - * @param string $field What kind of cell to return - * @param array $event An array of routine data + * @param array $routine An array of routine data + * @param string $rowclass Empty or one of ['even'|'odd'] * * @return string HTML code of a cell for the list of events */ diff --git a/libraries/rte/rte_routines.lib.php b/libraries/rte/rte_routines.lib.php index ca6d22d9e9..de1da104a4 100644 --- a/libraries/rte/rte_routines.lib.php +++ b/libraries/rte/rte_routines.lib.php @@ -7,6 +7,15 @@ if (! defined('PHPMYADMIN')) { exit; } +/** + * This function is defined in: rte_routines.lib.php, rte_triggers.lib.php and + * rte_events.lib.php. It is used to retreive some language strings that are + * used in functionalities that are common to routines, triggers and events. + * + * @param string $index The index of the string to get + * + * @return string The requested string or an empty string, if not available + */ function PMA_RTE_getWord($index) { $words = array( @@ -20,7 +29,7 @@ function PMA_RTE_getWord($index) 'title' => __('Routines'), ); return isset($words[$index]) ? $words[$index] : ''; -} +} // end PMA_RTE_getWord() /** * Main function for the routines functionality @@ -331,6 +340,9 @@ function PMA_RTN_getRoutineDataFromName($name, $all = true) return $retval; } // PMA_RTN_getRoutineDataFromName() +/** + * Handles editor requests for adding or editing an item + */ function PMA_RTN_handleEditor() { global $_GET, $_POST, $_REQUEST, $GLOBALS, $db, $cfg, $errors; @@ -479,10 +491,10 @@ function PMA_RTN_handleEditor() } } } -} +} // end PMA_RTN_handleEditor() /** - * This function will generate the values that are required to complete the "Add new routine" form + * This function will generate the values that are required to complete the editor form * It is especially necessary to handle the 'Add another parameter', 'Remove last parameter' * and 'Change routine type' functionalities when JS is disabled. * @@ -862,16 +874,16 @@ function PMA_RTN_getParameterRow($routine = array(), $index = null, $class = '') * or add a new one: 'edit' or 'add'. * @param string $operation If the editor was previously invoked with * JS turned off, this will hold the name of - * the current operation: 'add', remove', 'change' + * the current operation * @param array $routine Data for the routine returned by - * PMA_RTN_getRoutineDataFromRequest() or - * PMA_RTN_getRoutineDataFromName() + * PMA_RTN_getDataFromRequest() or + * PMA_RTN_getDataFromName() * @param array $errors If the editor was already invoked and there * has been an error while processing the request * this array will hold the errors. * @param bool $is_ajax True, if called from an ajax request * - * @return string HTML code for the routine editor. + * @return string HTML code for the editor. */ function PMA_RTN_getEditorForm($mode, $operation, $routine, $errors, $is_ajax) { @@ -1094,6 +1106,9 @@ function PMA_RTN_getEditorForm($mode, $operation, $routine, $errors, $is_ajax) return $retval; } // end PMA_RTN_getEditorForm() +/** + * Handles requests for executing a routine + */ function PMA_RTN_handleExecute() { global $_GET, $_POST, $_REQUEST, $GLOBALS, $db, $cfg; @@ -1153,7 +1168,7 @@ function PMA_RTN_handleExecute() break; } while (true) { - if(! PMA_DBI_more_results()) { + if (! PMA_DBI_more_results()) { break; } PMA_DBI_next_result(); @@ -1268,7 +1283,7 @@ function PMA_RTN_handleExecute() * Creates the HTML code that shows the routine execution dialog. * * @param array $routine Data for the routine returned by - * PMA_RTN_getRoutineDataFromName() + * PMA_RTN_getDataFromName() * @param bool $is_ajax True, if called from an ajax request * * @return string HTML code for the routine execution dialog. diff --git a/libraries/rte/rte_triggers.lib.php b/libraries/rte/rte_triggers.lib.php index 0da8cc61a3..89b3e952cc 100644 --- a/libraries/rte/rte_triggers.lib.php +++ b/libraries/rte/rte_triggers.lib.php @@ -7,6 +7,15 @@ if (! defined('PHPMYADMIN')) { exit; } +/** + * This function is defined in: rte_routines.lib.php, rte_triggers.lib.php and + * rte_events.lib.php. It is used to retreive some language strings that are + * used in functionalities that are common to routines, triggers and events. + * + * @param string $index The index of the string to get + * + * @return string The requested string or an empty string, if not available + */ function PMA_RTE_getWord($index) { $words = array( @@ -20,7 +29,7 @@ function PMA_RTE_getWord($index) 'title' => __('Triggers'), ); return isset($words[$index]) ? $words[$index] : ''; -} +} // end PMA_RTE_getWord() /** * Main function for the triggers functionality @@ -46,6 +55,9 @@ function PMA_RTE_main() echo PMA_TRI_getFooterLinks(); } // end PMA_RTE_main() +/** + * Handles editor requests for adding or editing an item + */ function PMA_TRI_handleEditor() { global $_REQUEST, $_POST, $errors, $db, $table; @@ -182,10 +194,10 @@ function PMA_TRI_handleEditor() } } } -} +} // end PMA_TRI_handleEditor() /** - * This function will generate the values that are required to for the ditor + * This function will generate the values that are required to for the editor * * @return array Data necessary to create the editor. */ @@ -240,6 +252,20 @@ function PMA_TRI_getDataFromName($name) } } // end PMA_TRI_getDataFromName() +/** + * Displays a form used to add/edit a trigger + * + * @param string $mode If the editor will be used edit a trigger + * or add a new one: 'edit' or 'add'. + * @param string $operation If the editor was previously invoked with + * JS turned off, this will hold the name of + * the current operation + * @param array $item Data for the trigger returned by + * PMA_TRI_getDataFromRequest() or + * PMA_TRI_getDataFromName() + * + * @return string HTML code for the editor. + */ function PMA_TRI_getEditorForm($mode, $item) { global $db, $table, $titles, $event_manipulations, $action_timings; @@ -337,7 +363,7 @@ function PMA_TRI_getEditorForm($mode, $item) $retval .= "\n\n"; return $retval; -} +} // end PMA_TRI_getEditorForm() /** * Composes the query necessary to create a trigger from an HTTP request.