Docblock improvements
diff --git a/system/core/Benchmark.php b/system/core/Benchmark.php
index 2fabdf4..f94db27 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 @@
// --------------------------------------------------------------------
/**
+ * 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 @@
* 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 @@
/**
* 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 9196958..8c2ba89 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 @@
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 bd9178d..c0caf2e 100644
--- a/system/core/Exceptions.php
+++ b/system/core/Exceptions.php
@@ -64,7 +64,7 @@
);
/**
- * Initialize execption class
+ * Class constructor
*
* @return void
*/
@@ -79,12 +79,12 @@
/**
* 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 @@
// --------------------------------------------------------------------
/**
- * 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 @@
/**
* 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 the heading
- * @param string the message
- * @param string the template name
- * @param int the status code
- * @return string
+ * @param string $heading Page heading
+ * @param string|string[] $message Error message
+ * @param string $template Template name
+ * @param int $statis_code (default: 500)
+ *
+ * @return string Error page output
*/
public function show_error($heading, $message, $template = 'error_general', $status_code = 500)
{
@@ -154,11 +156,11 @@
/**
* 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 afbf4b4..d60e9ac 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 @@
/**
* 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 @@
*
* 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 @@
*
* 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 @@
// 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 @@
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
- // -----------------------------------
+ // Set the _in_progress flag
+ $this->_in_progress = TRUE;
- $this->in_progress = TRUE;
-
- // -----------------------------------
// Call the requested class and/or function
- // -----------------------------------
-
if ($class !== FALSE)
{
if ( ! class_exists($class))
@@ -218,7 +198,7 @@
require($filepath);
}
- $HOOK = new $class;
+ $HOOK = new $class();
$HOOK->$function($params);
}
else
@@ -231,7 +211,7 @@
$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 601348a..e74304d 100644
--- a/system/core/Lang.php
+++ b/system/core/Lang.php
@@ -39,19 +39,19 @@
/**
* 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 @@
/**
* 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 @@
// --------------------------------------------------------------------
/**
- * Fetch a single line of text from the language array
+ * Language line
*
- * @param string $line the language line
- * @return string
+ * Fetches a single line of text from the language array
+ *
+ * @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 9bc9f87..5a87ab1 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 @@
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 1ff0298..bc7afed 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 @@
/**
* 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 @@
*
* 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 @@
/**
* 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 @@
/**
* 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 37f7a28..f6ea412 100644
--- a/system/database/drivers/odbc/odbc_driver.php
+++ b/system/database/drivers/odbc/odbc_driver.php
@@ -50,7 +50,9 @@
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 3be7e3c..d64e9fb 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 @@
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 3efc45a..93674b5 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 @@
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 91d9a23..ca231f6 100644
--- a/system/database/drivers/postgre/postgre_driver.php
+++ b/system/database/drivers/postgre/postgre_driver.php
@@ -47,7 +47,9 @@
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 a49f171..95f537e 100644
--- a/system/libraries/Calendar.php
+++ b/system/libraries/Calendar.php
@@ -95,11 +95,13 @@
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())