From 3e9d2b8ae82948de3c83bd5a50151949f6e6ca90 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 27 Oct 2012 14:28:51 +0300 Subject: Docblock improvements --- system/core/Benchmark.php | 32 +++++----- system/core/Controller.php | 11 ++-- system/core/Exceptions.php | 48 +++++++-------- system/core/Hooks.php | 68 ++++++++-------------- system/core/Lang.php | 27 +++++---- system/core/Model.php | 10 ++-- system/core/Utf8.php | 26 +++++---- system/database/drivers/odbc/odbc_driver.php | 4 +- .../drivers/pdo/subdrivers/pdo_odbc_driver.php | 4 +- .../drivers/pdo/subdrivers/pdo_pgsql_driver.php | 4 +- system/database/drivers/postgre/postgre_driver.php | 4 +- system/libraries/Calendar.php | 8 ++- 12 files changed, 125 insertions(+), 121 deletions(-) (limited to 'system') diff --git a/system/core/Benchmark.php b/system/core/Benchmark.php index 2fabdf46e..f94db2721 100644 --- a/system/core/Benchmark.php +++ b/system/core/Benchmark.php @@ -26,7 +26,7 @@ */ /** - * CodeIgniter Benchmark Class + * Benchmark Class * * This class enables you to mark points and calculate the time difference * between them. Memory consumption can also be displayed. @@ -40,21 +40,19 @@ class CI_Benchmark { /** - * List of all benchmark markers and when they were added + * List of all benchmark markers * - * @var array + * @var array */ - public $marker = array(); - - // -------------------------------------------------------------------- + public $marker = array(); /** * Set a benchmark marker * * Multiple calls to this function can be made so that several - * execution points can be timed + * execution points can be timed. * - * @param string $name name of the marker + * @param string $name Marker name * @return void */ public function mark($name) @@ -65,6 +63,8 @@ class CI_Benchmark { // -------------------------------------------------------------------- /** + * Elapsed time + * * Calculates the time difference between two marked points. * * If the first parameter is empty this function instead returns the @@ -72,10 +72,13 @@ class CI_Benchmark { * execution time to be shown in a template. The output class will * swap the real value for this variable. * - * @param string a particular marked point - * @param string a particular marked point - * @param integer the number of decimal places - * @return mixed + * @param string $point1 A particular marked point + * @param string $point2 A particular marked point + * @param int $decimals Number of decimal places + * + * @return string Calculated elapsed time on success, + * an '{elapsed_string}' if $point1 is empty + * or an empty string if $point1 is not found. */ public function elapsed_time($point1 = '', $point2 = '', $decimals = 4) { @@ -102,12 +105,13 @@ class CI_Benchmark { /** * Memory Usage * - * This function returns the {memory_usage} pseudo-variable. + * Simply returns the {memory_usage} marker. + * * This permits it to be put it anywhere in a template * without the memory being calculated until the end. * The output class will swap the real value for this variable. * - * @return string + * @return string '{memory_usage}' */ public function memory_usage() { diff --git a/system/core/Controller.php b/system/core/Controller.php index 9196958ae..8c2ba893e 100644 --- a/system/core/Controller.php +++ b/system/core/Controller.php @@ -26,7 +26,7 @@ */ /** - * CodeIgniter Application Controller Class + * Application Controller Class * * This class object is the super class that every library in * CodeIgniter will be assigned to. @@ -40,15 +40,14 @@ class CI_Controller { /** - * Reference to the global CI instance + * Reference to the CI singleton * - * @static * @var object */ private static $instance; /** - * Set up controller properties and methods + * Class constructor * * @return void */ @@ -69,8 +68,10 @@ class CI_Controller { log_message('debug', 'Controller Class Initialized'); } + // -------------------------------------------------------------------- + /** - * Return the CI object + * Get the CI singleton * * @static * @return object diff --git a/system/core/Exceptions.php b/system/core/Exceptions.php index bd9178dbd..c0caf2e7d 100644 --- a/system/core/Exceptions.php +++ b/system/core/Exceptions.php @@ -64,7 +64,7 @@ class CI_Exceptions { ); /** - * Initialize execption class + * Class constructor * * @return void */ @@ -79,12 +79,12 @@ class CI_Exceptions { /** * Exception Logger * - * This function logs PHP generated error messages + * Logs PHP generated error messages * - * @param string the error severity - * @param string the error string - * @param string the error filepath - * @param string the error line number + * @param int $severity Log level + * @param string $message Error message + * @param string $filepath File path + * @param int $line Line number * @return void */ public function log_exception($severity, $message, $filepath, $line) @@ -96,11 +96,13 @@ class CI_Exceptions { // -------------------------------------------------------------------- /** - * 404 Page Not Found Handler + * 404 Error Handler * - * @param string the page - * @param bool log error yes/no - * @return string + * @uses CI_Exceptions::show_error() + * + * @param string $page Page URI + * @param bool $log_error Whether to log the error + * @return void */ public function show_404($page = '', $log_error = TRUE) { @@ -122,15 +124,15 @@ class CI_Exceptions { /** * General Error Page * - * This function takes an error message as input - * (either as a string or an array) and displays - * it using the specified template. + * Takes an error message as input (either as a string or an array) + * and displays it using the specified template. + * + * @param string $heading Page heading + * @param string|string[] $message Error message + * @param string $template Template name + * @param int $statis_code (default: 500) * - * @param string the heading - * @param string the message - * @param string the template name - * @param int the status code - * @return string + * @return string Error page output */ public function show_error($heading, $message, $template = 'error_general', $status_code = 500) { @@ -154,11 +156,11 @@ class CI_Exceptions { /** * Native PHP error handler * - * @param string the error severity - * @param string the error string - * @param string the error filepath - * @param string the error line number - * @return string + * @param int $severity Error level + * @param string $message Error message + * @param string $filepath File path + * @param int $line Line number + * @return string Error page output */ public function show_php_error($severity, $message, $filepath, $line) { diff --git a/system/core/Hooks.php b/system/core/Hooks.php index afbf4b453..d60e9ac5d 100644 --- a/system/core/Hooks.php +++ b/system/core/Hooks.php @@ -26,7 +26,7 @@ */ /** - * CodeIgniter Hooks Class + * Hooks Class * * Provides a mechanism to extend the base system without hacking. * @@ -41,26 +41,28 @@ class CI_Hooks { /** * Determines whether hooks are enabled * - * @var bool + * @var bool */ - public $enabled = FALSE; + public $enabled = FALSE; /** * List of all hooks set in config/hooks.php * - * @var array + * @var array */ public $hooks = array(); /** + * In progress flag + * * Determines whether hook is in progress, used to prevent infinte loops * - * @var bool + * @var bool */ - public $in_progress = FALSE; + protected $_in_progress = FALSE; /** - * Initialize the Hooks Preferences + * Class constructor * * @return void */ @@ -104,8 +106,10 @@ class CI_Hooks { * * Calls a particular hook. Called by CodeIgniter.php. * - * @param string the hook name - * @return mixed + * @uses CI_Hooks::_run_hook() + * + * @param string $which Hook name + * @return bool TRUE on success or FALSE on failure */ public function call_hook($which = '') { @@ -136,8 +140,8 @@ class CI_Hooks { * * Runs a particular hook * - * @param array the hook details - * @return bool + * @param array $data Hook details + * @return bool TRUE on success or FALSE on failure */ protected function _run_hook($data) { @@ -152,7 +156,7 @@ class CI_Hooks { // If the script being called happens to have the same // hook call within it a loop can happen - if ($this->in_progress === TRUE) + if ($this->_in_progress === TRUE) { return; } @@ -173,44 +177,20 @@ class CI_Hooks { return FALSE; } - // ----------------------------------- - // Set class/function name - // ----------------------------------- - - $class = FALSE; - $function = FALSE; - $params = ''; - - if ( ! empty($data['class'])) - { - $class = $data['class']; - } - - if ( ! empty($data['function'])) - { - $function = $data['function']; - } - - if (isset($data['params'])) - { - $params = $data['params']; - } + // Determine and class and/or function names + $class = empty($data['class']) ? FALSE : $data['class']; + $function = empty($data['function']) ? FALSE : $data['function']; + $params = isset($data['params']) ? $data['params'] : ''; if ($class === FALSE && $function === FALSE) { return FALSE; } - // ----------------------------------- - // Set the in_progress flag - // ----------------------------------- - - $this->in_progress = TRUE; + // Set the _in_progress flag + $this->_in_progress = TRUE; - // ----------------------------------- // Call the requested class and/or function - // ----------------------------------- - if ($class !== FALSE) { if ( ! class_exists($class)) @@ -218,7 +198,7 @@ class CI_Hooks { require($filepath); } - $HOOK = new $class; + $HOOK = new $class(); $HOOK->$function($params); } else @@ -231,7 +211,7 @@ class CI_Hooks { $function($params); } - $this->in_progress = FALSE; + $this->_in_progress = FALSE; return TRUE; } diff --git a/system/core/Lang.php b/system/core/Lang.php index 601348aa4..e74304dd9 100644 --- a/system/core/Lang.php +++ b/system/core/Lang.php @@ -39,19 +39,19 @@ class CI_Lang { /** * List of translations * - * @var array + * @var array */ public $language = array(); /** * List of loaded language files * - * @var array + * @var array */ public $is_loaded = array(); /** - * Initialize language class + * Class constructor * * @return void */ @@ -65,12 +65,13 @@ class CI_Lang { /** * Load a language file * - * @param mixed $langile the name of the language file to be loaded - * @param string $idiom = '' the language (english, etc.) - * @param bool $return = FALSE return loaded array of translations - * @param bool $add_suffix = TRUE add suffix to $langfile - * @param string $alt_path = '' alternative path to look for language file - * @return mixed + * @param mixed $langfile Language file name + * @param string $idiom Language name (english, etc.) + * @param bool $return Whether to return the loaded array of translations + * @param bool $add_suffix Whether to add suffix to $langfile + * @param string $alt_path Alternative path to look for the language file + * + * @return void|string[] Array containing translations, if $return is set to TRUE */ public function load($langfile, $idiom = '', $return = FALSE, $add_suffix = TRUE, $alt_path = '') { @@ -146,10 +147,12 @@ class CI_Lang { // -------------------------------------------------------------------- /** - * Fetch a single line of text from the language array + * Language line + * + * Fetches a single line of text from the language array * - * @param string $line the language line - * @return string + * @param string $line Language line key + * @return string Translation */ public function line($line = '') { diff --git a/system/core/Model.php b/system/core/Model.php index 9bc9f879f..5a87ab153 100644 --- a/system/core/Model.php +++ b/system/core/Model.php @@ -26,7 +26,7 @@ */ /** - * CodeIgniter Model Class + * Model Class * * @package CodeIgniter * @subpackage Libraries @@ -37,7 +37,7 @@ class CI_Model { /** - * Initialize CI_Model Class + * Class constructor * * @return void */ @@ -46,13 +46,15 @@ class CI_Model { log_message('debug', 'Model Class Initialized'); } + // -------------------------------------------------------------------- + /** - * __get + * __get magic * * Allows models to access CI's loaded classes using the same * syntax as controllers. * - * @param string + * @param string $key */ public function __get($key) { diff --git a/system/core/Utf8.php b/system/core/Utf8.php index 1ff02981b..bc7afed91 100644 --- a/system/core/Utf8.php +++ b/system/core/Utf8.php @@ -39,9 +39,9 @@ class CI_Utf8 { /** - * Constructor + * Class constructor * - * Determines if UTF-8 support is to be enabled + * Determines if UTF-8 support is to be enabled. * * @return void */ @@ -87,9 +87,11 @@ class CI_Utf8 { /** * Clean UTF-8 strings * - * Ensures strings are UTF-8 + * Ensures strings contain only valid UTF-8 characters. * - * @param string + * @uses CI_Utf8::_is_ascii() Decide whether a conversion is needed + * + * @param string $str String to clean * @return string */ public function clean_string($str) @@ -109,9 +111,9 @@ class CI_Utf8 { * * Removes all ASCII control characters except horizontal tabs, * line feeds, and carriage returns, as all others can cause - * problems in XML + * problems in XML. * - * @param string + * @param string $str String to clean * @return string */ public function safe_ascii_for_xml($str) @@ -124,11 +126,11 @@ class CI_Utf8 { /** * Convert to UTF-8 * - * Attempts to convert a string to UTF-8 + * Attempts to convert a string to UTF-8. * - * @param string - * @param string input encoding - * @return string + * @param string $str Input string + * @param string $encoding Input encoding + * @return string $str encoded in UTF-8 or FALSE on failure */ public function convert_to_utf8($str, $encoding) { @@ -149,9 +151,9 @@ class CI_Utf8 { /** * Is ASCII? * - * Tests if a string is standard 7-bit ASCII or not + * Tests if a string is standard 7-bit ASCII or not. * - * @param string + * @param string $str String to check * @return bool */ protected function _is_ascii($str) diff --git a/system/database/drivers/odbc/odbc_driver.php b/system/database/drivers/odbc/odbc_driver.php index 37f7a28d3..f6ea412ad 100644 --- a/system/database/drivers/odbc/odbc_driver.php +++ b/system/database/drivers/odbc/odbc_driver.php @@ -50,7 +50,9 @@ class CI_DB_odbc_driver extends CI_DB { protected $_random_keyword; /** - * @var string Database schema + * Database schema + * + * @var string */ public $schema = 'public'; diff --git a/system/database/drivers/pdo/subdrivers/pdo_odbc_driver.php b/system/database/drivers/pdo/subdrivers/pdo_odbc_driver.php index 3be7e3c70..d64e9fb36 100644 --- a/system/database/drivers/pdo/subdrivers/pdo_odbc_driver.php +++ b/system/database/drivers/pdo/subdrivers/pdo_odbc_driver.php @@ -51,7 +51,9 @@ class CI_DB_pdo_odbc_driver extends CI_DB_pdo_driver { protected $_random_keyword = ' RAND()'; /** - * @var string Database schema + * Database schema + * + * @var string */ public $schema = 'public'; diff --git a/system/database/drivers/pdo/subdrivers/pdo_pgsql_driver.php b/system/database/drivers/pdo/subdrivers/pdo_pgsql_driver.php index 3efc45a2d..93674b576 100644 --- a/system/database/drivers/pdo/subdrivers/pdo_pgsql_driver.php +++ b/system/database/drivers/pdo/subdrivers/pdo_pgsql_driver.php @@ -45,7 +45,9 @@ class CI_DB_pdo_pgsql_driver extends CI_DB_pdo_driver { protected $_random_keyword = ' RANDOM()'; /** - * @var string Database schema + * Database schema + * + * @var string */ public $schema = 'public'; diff --git a/system/database/drivers/postgre/postgre_driver.php b/system/database/drivers/postgre/postgre_driver.php index 91d9a2385..ca231f6f7 100644 --- a/system/database/drivers/postgre/postgre_driver.php +++ b/system/database/drivers/postgre/postgre_driver.php @@ -47,7 +47,9 @@ class CI_DB_postgre_driver extends CI_DB { protected $_random_keyword = ' RANDOM()'; // database specific random keyword /** - * @var string Database schema + * Database schema + * + * @var string */ public $schema = 'public'; diff --git a/system/libraries/Calendar.php b/system/libraries/Calendar.php index a49f171b9..95f537e42 100644 --- a/system/libraries/Calendar.php +++ b/system/libraries/Calendar.php @@ -95,11 +95,13 @@ class CI_Calendar { public $next_prev_url = ''; /** - * Constructor + * Class constructor * - * Loads the calendar language file and sets the default time reference + * Loads the calendar language file and sets the default time reference. * - * @param array + * @uses CI_Lang::$is_loaded + * + * @param array $config Calendar options * @return void */ public function __construct($config = array()) -- cgit v1.2.3-24-g4f1b