Docblock improvements

7 files changed, 108 insertions, 114 deletions

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)