From ae85eb42aa2d5c6d9a41b3cf6c61a4bf1c9b0566 Mon Sep 17 00:00:00 2001
From: Andrey Andreev <narf@bofh.bg>
Date: Fri, 2 Nov 2012 01:42:31 +0200
Subject: DocBlocks for base DB classes

Partially fixes issue #1295.
---
 system/database/DB.php               |  17 +-
 system/database/DB_cache.php         |  26 +-
 system/database/DB_driver.php        | 263 +++++++++++++++++++-
 system/database/DB_forge.php         |  51 +++-
 system/database/DB_query_builder.php | 460 ++++++++++++++++++++++++-----------
 system/database/DB_result.php        | 200 +++++++++++++--
 system/database/DB_utility.php       |  44 ++--
 7 files changed, 864 insertions(+), 197 deletions(-)

(limited to 'system')

diff --git a/system/database/DB.php b/system/database/DB.php
index 676cb9ccd..79e5c7ad2 100644
--- a/system/database/DB.php
+++ b/system/database/DB.php
@@ -32,8 +32,10 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  * @category	Database
  * @author	EllisLab Dev Team
  * @link	http://codeigniter.com/user_guide/database/
- * @param 	string
- * @param 	bool	Determines if query builder should be used or not
+ *
+ * @param 	string|string[]	$params
+ * @param 	bool		$query_builder_override
+ *				Determines if query builder should be used or not
  */
 function &DB($params = '', $query_builder_override = NULL)
 {
@@ -149,11 +151,22 @@ function &DB($params = '', $query_builder_override = NULL)
 		require_once(BASEPATH.'database/DB_query_builder.php');
 		if ( ! class_exists('CI_DB'))
 		{
+			/**
+			 * CI_DB
+			 *
+			 * Acts as an alias for both CI_DB_driver and CI_DB_query_builder.
+			 *
+			 * @see	CI_DB_query_builder
+			 * @see	CI_DB_driver
+			 */
 			class CI_DB extends CI_DB_query_builder { }
 		}
 	}
 	elseif ( ! class_exists('CI_DB'))
 	{
+		/**
+	 	 * @ignore
+		 */
 		class CI_DB extends CI_DB_driver { }
 	}
 
diff --git a/system/database/DB_cache.php b/system/database/DB_cache.php
index 37d2dd0b5..b8f8995fa 100644
--- a/system/database/DB_cache.php
+++ b/system/database/DB_cache.php
@@ -35,8 +35,24 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 class CI_DB_Cache {
 
+	/**
+	 * CI Singleton
+	 *
+	 * @var	object
+	 */
 	public $CI;
-	public $db;	// allows passing of db object so that multiple database connections and returned db objects can be supported
+
+	/**
+	 * Database object
+	 *
+	 * Allows passing of DB object so that multiple database connections
+	 * and returned DB objects can be supported.
+	 *
+	 * @var	object
+	 */
+	public $db;
+
+	// --------------------------------------------------------------------
 
 	/**
 	 * Constructor
@@ -59,7 +75,7 @@ class CI_DB_Cache {
 	/**
 	 * Set Cache Directory Path
 	 *
-	 * @param	string	the path to the cache directory
+	 * @param	string	$path	Path to the cache directory
 	 * @return	bool
 	 */
 	public function check_path($path = '')
@@ -95,7 +111,7 @@ class CI_DB_Cache {
 	 * Retrieve a cached query
 	 *
 	 * The URI being requested will become the name of the cache sub-folder.
-	 * An MD5 hash of the SQL statement will become the cache file name
+	 * An MD5 hash of the SQL statement will become the cache file name.
 	 *
 	 * @param	string	$sql
 	 * @return	string
@@ -154,8 +170,8 @@ class CI_DB_Cache {
 	/**
 	 * Delete cache files within a particular directory
 	 *
-	 * @param	string	$segment_one = ''
-	 * @param	string	$segment_two = ''
+	 * @param	string	$segment_one
+	 * @param	string	$segment_two
 	 * @return	void
 	 */
 	public function delete($segment_one = '', $segment_two = '')
diff --git a/system/database/DB_driver.php b/system/database/DB_driver.php
index 515e9cbb1..497f8b9c9 100644
--- a/system/database/DB_driver.php
+++ b/system/database/DB_driver.php
@@ -41,60 +41,300 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 abstract class CI_DB_driver {
 
+	/**
+	 * Data Source Name / Connect string
+	 *
+	 * @var	string
+	 */
 	public $dsn;
+
+	/**
+	 * Username
+	 *
+	 * @var	string
+	 */
 	public $username;
+
+	/**
+	 * Password
+	 *
+	 * @var	string
+	 */
 	public $password;
+
+	/**
+	 * Hostname
+	 *
+	 * @var	string
+	 */
 	public $hostname;
+
+	/**
+	 * Database name
+	 *
+	 * @var	string
+	 */
 	public $database;
+
+	/**
+	 * Database driver
+	 *
+	 * @var	string
+	 */
 	public $dbdriver		= 'mysqli';
+
+	/**
+	 * Sub-driver
+	 *
+	 * @used-by	CI_DB_pdo_driver
+	 * @var	string
+	 */
 	public $subdriver;
+
+	/**
+	 * Table prefix
+	 *
+	 * @var	string
+	 */
 	public $dbprefix		= '';
+
+	/**
+	 * Character set
+	 *
+	 * @var	string
+	 */
 	public $char_set		= 'utf8';
+
+	/**
+	 * Collation
+	 *
+	 * @var	string
+	 */
 	public $dbcollat		= 'utf8_general_ci';
-	public $autoinit		= TRUE; // Whether to automatically initialize the DB
+
+	/**
+	 * Auto-init flag
+	 *
+	 * Whether to automatically initialize the DB connection.
+	 *
+	 * @var	bool
+	 */
+	public $autoinit		= TRUE;
+
+	/**
+	 * Encryption flag/data
+	 *
+	 * @var	mixed
+	 */
 	public $encrypt			= FALSE;
+
+	/**
+	 * Swap Prefix
+	 *
+	 * @var	string
+	 */
 	public $swap_pre		= '';
+
+	/**
+	 * Database port
+	 *
+	 * @var	int
+	 */
 	public $port			= '';
+
+	/**
+	 * Persistent connection flag
+	 *
+	 * @var	bool
+	 */
 	public $pconnect		= FALSE;
+
+	/**
+	 * Connection ID
+	 *
+	 * @var	object|resource
+	 */
 	public $conn_id			= FALSE;
+
+	/**
+	 * Result ID
+	 *
+	 * @var	object|resource
+	 */
 	public $result_id		= FALSE;
+
+	/**
+	 * Debug flag
+	 *
+	 * Whether to display error messages.
+	 *
+	 * @var	bool
+	 */
 	public $db_debug		= FALSE;
+
+	/**
+	 * Benchmark time
+	 *
+	 * @var	int
+	 */
 	public $benchmark		= 0;
+
+	/**
+	 * Executed queries count
+	 *
+	 * @var	int
+	 */
 	public $query_count		= 0;
+
+	/**
+	 * Bind marker
+	 *
+	 * Character used to identify values in a prepared statement.
+	 *
+	 * @var	string
+	 */
 	public $bind_marker		= '?';
+
+	/**
+	 * Save queries flag
+	 *
+	 * Whether to keep an in-memory history of queries for debugging purposes.
+	 *
+	 * @var	bool
+	 */
 	public $save_queries		= TRUE;
+
+	/**
+	 * Queries list
+	 *
+	 * @see	CI_DB_driver::$save_queries
+	 * @var	string[]
+	 */
 	public $queries			= array();
+
+	/**
+	 * Query times
+	 *
+	 * A list of times that queries took to execute.
+	 *
+	 * @var	array
+	 */
 	public $query_times		= array();
+
+	/**
+	 * Data cache
+	 *
+	 * An internal generic value cache.
+	 *
+	 * @var	array
+	 */
 	public $data_cache		= array();
 
+	/**
+	 * Transaction enabled flag
+	 *
+	 * @var	bool
+	 */
 	public $trans_enabled		= TRUE;
+
+	/**
+	 * Strict transaction mode flag
+	 *
+	 * @var	bool
+	 */
 	public $trans_strict		= TRUE;
+
+	/**
+	 * Transaction depth level
+	 *
+	 * @var	int
+	 */
 	protected $_trans_depth		= 0;
-	protected $_trans_status	= TRUE; // Used with transactions to determine if a rollback should occur
 
+	/**
+	 * Transaction status flag
+	 *
+	 * Used with transactions to determine if a rollback should occur.
+	 *
+	 * @var	bool
+	 */
+	protected $_trans_status	= TRUE;
+
+	/**
+	 * Cache On flag
+	 *
+	 * @var	bool
+	 */
 	public $cache_on		= FALSE;
+
+	/**
+	 * Cache directory path
+	 *
+	 * @var	bool
+	 */
 	public $cachedir		= '';
+
+	/**
+	 * Cache auto-delete flag
+	 *
+	 * @var	bool
+	 */
 	public $cache_autodel		= FALSE;
-	public $CACHE; // The cache class object
 
+	/**
+	 * DB Cache object
+	 *
+	 * @see	CI_DB_cache
+	 * @var	object
+	 */
+	public $CACHE;
+
+	/**
+	 * Protect identifiers flag
+	 *
+	 * @var	bool
+	 */
 	protected $_protect_identifiers		= TRUE;
-	protected $_reserved_identifiers	= array('*'); // Identifiers that should NOT be escaped
 
-	// clause and character used for LIKE escape sequences
+	/**
+	 * List of reserved identifiers
+	 *
+	 * Identifiers that must NOT be escaped.
+	 *
+	 * @var	string[]
+	 */
+	protected $_reserved_identifiers	= array('*');
+
+	/**
+	 * ESCAPE statement string
+	 *
+	 * @var	string
+	 */
 	protected $_like_escape_str = " ESCAPE '%s' ";
+
+	/**
+	 * ESCAPE character
+	 *
+	 * @var	string
+	 */
 	protected $_like_escape_chr = '!';
 
 	/**
-	 * The syntax to count rows is slightly different across different
-	 * database engines, so this string appears in each driver and is
-	 * used for the count_all() and count_all_results() functions.
+	 * COUNT string
+	 *
+	 * @used-by	CI_DB_driver::count_all()
+	 * @used-by	CI_DB_query_builder::count_all_results()
+	 *
+	 * @var	string
 	 */
 	protected $_count_string = 'SELECT COUNT(*) AS ';
 
+	// --------------------------------------------------------------------
+
 	/**
-	 * Constructor
+	 * Class constructor
 	 *
-	 * @param	array
+	 * @param	array	$params
 	 * @return	void
 	 */
 	public function __construct($params)
@@ -1175,8 +1415,7 @@ abstract class CI_DB_driver {
 	/**
 	 * Enables a native PHP function to be run, using a platform agnostic wrapper.
 	 *
-	 * @param	string	$function	the function name
-	 * @param	mixed	$param,...	optional parameters needed by the function
+	 * @param	string	$function	Function name
 	 * @return	mixed
 	 */
 	public function call_function($function)
diff --git a/system/database/DB_forge.php b/system/database/DB_forge.php
index 50b55d60e..d2d99ccea 100644
--- a/system/database/DB_forge.php
+++ b/system/database/DB_forge.php
@@ -35,17 +35,66 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 abstract class CI_DB_forge {
 
+	/**
+	 * Fields data
+	 *
+	 * @var	array
+	 */
 	public $fields		= array();
+
+	/**
+	 * Keys data
+	 *
+	 * @var	array
+	 */
 	public $keys		= array();
+
+	/**
+	 * Primary Keys data
+	 *
+	 * @var	array
+	 */
 	public $primary_keys	= array();
+
+	/**
+	 * Database character set
+	 *
+	 * @var	string
+	 */
 	public $db_char_set	= '';
 
-	// Platform specific SQL strings
+	// --------------------------------------------------------------------
+
+	/**
+	 * CREATE DATABASE statement
+	 *
+	 * @var	string
+	 */
 	protected $_create_database	= 'CREATE DATABASE %s';
+
+	/**
+	 * DROP DATABASE statement
+	 *
+	 * @var	string
+	 */
 	protected $_drop_database	= 'DROP DATABASE %s';
+
+	/**
+	 * DROP TABLE statement
+	 *
+	 * @var	string
+	 */
 	protected $_drop_table		= 'DROP TABLE IF EXISTS %s';
+
+	/**
+	 * RENAME TABLE statement
+	 *
+	 * @var	string
+	 */
 	protected $_rename_table	= 'ALTER TABLE %s RENAME TO %s';
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Constructor
 	 *
diff --git a/system/database/DB_query_builder.php b/system/database/DB_query_builder.php
index 75cad95de..41b30aec3 100644
--- a/system/database/DB_query_builder.php
+++ b/system/database/DB_query_builder.php
@@ -40,42 +40,213 @@ defined('BASEPATH') OR exit('No direct script access allowed');
 
 abstract class CI_DB_query_builder extends CI_DB_driver {
 
+	/**
+	 * Return DELETE SQL flag
+	 *
+	 * @var	bool
+	 */
 	protected $return_delete_sql		= FALSE;
+
+	/**
+	 * Reset DELETE data flag
+	 *
+	 * @var	bool
+	 */
 	protected $reset_delete_data		= FALSE;
 
+	/**
+	 * QB SELECT data
+	 *
+	 * @var	array
+	 */
 	protected $qb_select			= array();
+
+	/**
+	 * QB DISTINCT flag
+	 *
+	 * @var	bool
+	 */
 	protected $qb_distinct			= FALSE;
+
+	/**
+	 * QB FROM data
+	 *
+	 * @var	array
+	 */
 	protected $qb_from			= array();
+
+	/**
+	 * QB JOIN data
+	 *
+	 * @var	array
+	 */
 	protected $qb_join			= array();
+
+	/**
+	 * QB WHERE data
+	 *
+	 * @var	array
+	 */
 	protected $qb_where			= array();
+
+	/**
+	 * QB GROUP BY data
+	 *
+	 * @var	array
+	 */
 	protected $qb_groupby			= array();
+
+	/**
+	 * QB HAVING data
+	 *
+	 * @var	array
+	 */
 	protected $qb_having			= array();
+
+	/**
+	 * QB keys
+	 *
+	 * @var	array
+	 */
 	protected $qb_keys			= array();
+
+	/**
+	 * QB LIMIT data
+	 *
+	 * @var	int
+	 */
 	protected $qb_limit			= FALSE;
+
+	/**
+	 * QB OFFSET data
+	 *
+	 * @var	int
+	 */
 	protected $qb_offset			= FALSE;
+
+	/**
+	 * QB ORDER BY data
+	 *
+	 * @var	array
+	 */
 	protected $qb_orderby			= array();
+
+	/**
+	 * QB data sets
+	 *
+	 * @var	array
+	 */
 	protected $qb_set			= array();
+
+	/**
+	 * QB aliased tables list
+	 *
+	 * @var	array
+	 */
 	protected $qb_aliased_tables		= array();
-	protected $qb_store_array		= array();
+
+	/**
+	 * QB WHERE group started flag
+	 *
+	 * @var	bool
+	 */
 	protected $qb_where_group_started	= FALSE;
+
+	/**
+	 * QB WHERE group count
+	 *
+	 * @var	int
+	 */
 	protected $qb_where_group_count		= 0;
 
 	// Query Builder Caching variables
+
+	/**
+	 * QB Caching flag
+	 *
+	 * @var	bool
+	 */
 	protected $qb_caching				= FALSE;
+
+	/**
+	 * QB Cache exists list
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_exists			= array();
+
+	/**
+	 * QB Cache SELECT data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_select			= array();
+
+	/**
+	 * QB Cache FROM data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_from			= array();
+
+	/**
+	 * QB Cache JOIN data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_join			= array();
+
+	/**
+	 * QB Cache WHERE data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_where			= array();
-	protected $qb_cache_like			= array();
+
+	/**
+	 * QB Cache GROUP BY data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_groupby			= array();
+
+	/**
+	 * QB Cache HAVING data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_having			= array();
+
+	/**
+	 * QB Cache ORDER BY data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_orderby			= array();
+
+	/**
+	 * QB Cache data sets
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_set				= array();
 
+	/**
+	 * QB No Escape data
+	 *
+	 * @var	array
+	 */
 	protected $qb_no_escape 			= array();
+
+	/**
+	 * QB Cache No Escape data
+	 *
+	 * @var	array
+	 */
 	protected $qb_cache_no_escape			= array();
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Select
 	 *
@@ -183,17 +354,16 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Processing Function for the following functions:
-	 *
-	 *	select_max()
-	 *	select_min()
-	 *	select_avg()
-	 *	select_sum()
+	 * SELECT [MAX|MIN|AVG|SUM]()
 	 *
+	 * @used-by	select_max()
+	 * @used-by	select_min()
+	 * @used-by	select_avg()
+	 * @used-by	select_sum()
 	 *
-	 * @param	string	$select = ''	field name
-	 * @param	string	$alias = ''
-	 * @param	string	$type = 'MAX'
+	 * @param	string	$select	Field name
+	 * @param	string	$alias
+	 * @param	string	$type
 	 * @return	object
 	 */
 	protected function _max_min_avg_sum($select = '', $alias = '', $type = 'MAX')
@@ -234,7 +404,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	/**
 	 * Determines the alias name based on the table
 	 *
-	 * @param	string
+	 * @param	string	$item
 	 * @return	string
 	 */
 	protected function _create_alias_from_table($item)
@@ -255,7 +425,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	 *
 	 * Sets a flag which tells the query string compiler to add DISTINCT
 	 *
-	 * @param	bool
+	 * @param	bool	$val
 	 * @return	object
 	 */
 	public function distinct($val = TRUE)
@@ -271,7 +441,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	 *
 	 * Generates the FROM portion of the query
 	 *
-	 * @param	mixed	can be a string or array
+	 * @param	mixed	$from	can be a string or array
 	 * @return	object
 	 */
 	public function from($from)
@@ -318,7 +488,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Join
+	 * JOIN
 	 *
 	 * Generates the JOIN portion of the query
 	 *
@@ -406,10 +576,10 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Where
+	 * WHERE
 	 *
-	 * Generates the WHERE portion of the query. Separates
-	 * multiple calls with AND
+	 * Generates the WHERE portion of the query.
+	 * Separates multiple calls with 'AND'.
 	 *
 	 * @param	mixed
 	 * @param	mixed
@@ -424,10 +594,10 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * OR Where
+	 * OR WHERE
 	 *
-	 * Generates the WHERE portion of the query. Separates
-	 * multiple calls with OR
+	 * Generates the WHERE portion of the query.
+	 * Separates multiple calls with 'OR'.
 	 *
 	 * @param	mixed
 	 * @param	mixed
@@ -444,13 +614,16 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	/**
 	 * WHERE, HAVING
 	 *
-	 * Called by where(), or_where(), having(), or_having()
+	 * @used-by	where()
+	 * @used-by	or_where()
+	 * @used-by	having()
+	 * @used-by	or_having()
 	 *
-	 * @param	string	'qb_where' or 'qb_having'
-	 * @param	mixed
-	 * @param	mixed
-	 * @param	string
-	 * @param	bool
+	 * @param	string	$qb_key	'qb_where' or 'qb_having'
+	 * @param	mixed	$key
+	 * @param	mixed	$value
+	 * @param	string	$type
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	protected function _wh($qb_key, $key, $value = NULL, $type = 'AND ', $escape = NULL)
@@ -505,14 +678,14 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Where_in
+	 * WHERE IN
 	 *
-	 * Generates a WHERE field IN('item', 'item') SQL query joined with
-	 * AND if appropriate
+	 * Generates a WHERE field IN('item', 'item') SQL query,
+	 * joined with 'AND' if appropriate.
 	 *
-	 * @param	string	$key = NULL	The field to search
-	 * @param	array	$values = NULL	The values searched on
-	 * @param	bool	$escape = NULL
+	 * @param	string	$key	The field to search
+	 * @param	array	$values	The values searched on
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function where_in($key = NULL, $values = NULL, $escape = NULL)
@@ -523,14 +696,14 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Or_where_in
+	 * OR WHERE IN
 	 *
-	 * Generates a WHERE field IN('item', 'item') SQL query joined with
-	 * OR if appropriate
+	 * Generates a WHERE field IN('item', 'item') SQL query,
+	 * joined with 'OR' if appropriate.
 	 *
-	 * @param	string	$key = NULL	The field to search
-	 * @param	array	$values = NULL	The values searched on
-	 * @param	bool	$escape = NULL
+	 * @param	string	$key	The field to search
+	 * @param	array	$values	The values searched on
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function or_where_in($key = NULL, $values = NULL, $escape = NULL)
@@ -541,14 +714,14 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Where_not_in
+	 * WHERE NOT IN
 	 *
-	 * Generates a WHERE field NOT IN('item', 'item') SQL query joined
-	 * with AND if appropriate
+	 * Generates a WHERE field NOT IN('item', 'item') SQL query,
+	 * joined with 'AND' if appropriate.
 	 *
-	 * @param	string	$key = NULL	The field to search
-	 * @param	array	$values = NULL	The values searched on
-	 * @param	bool	$escape = NULL
+	 * @param	string	$key	The field to search
+	 * @param	array	$values	The values searched on
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function where_not_in($key = NULL, $values = NULL, $escape = NULL)
@@ -559,14 +732,14 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Or_where_not_in
+	 * OR WHERE NOT IN
 	 *
-	 * Generates a WHERE field NOT IN('item', 'item') SQL query joined
-	 * with OR if appropriate
+	 * Generates a WHERE field NOT IN('item', 'item') SQL query,
+	 * joined with 'OR' if appropriate.
 	 *
-	 * @param	string	$key = NULL	The field to search
-	 * @param	array	$values = NULL	The values searched on
-	 * @param	bool	$escape = NULL
+	 * @param	string	$key	The field to search
+	 * @param	array	$values	The values searched on
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function or_where_not_in($key = NULL, $values = NULL, $escape = NULL)
@@ -577,15 +750,18 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Where_in
+	 * Internal WHERE IN
 	 *
-	 * Called by where_in(), or_where_in(), where_not_in(), or_where_not_in()
+	 * @used-by	where_in()
+	 * @used-by	or_where_in()
+	 * @used-by	where_not_in()
+	 * @used-by	or_where_not_in()
 	 *
-	 * @param	string	$key = NULL	The field to search
-	 * @param	array	$values = NULL	The values searched on
-	 * @param	bool	$not = FALSE	If the statement would be IN or NOT IN
-	 * @param	string	$type = 'AND '
-	 * @param	bool	$escape = NULL
+	 * @param	string	$key	The field to search
+	 * @param	array	$values	The values searched on
+	 * @param	bool	$not	If the statement would be IN or NOT IN
+	 * @param	string	$type
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	protected function _where_in($key = NULL, $values = NULL, $not = FALSE, $type = 'AND ', $escape = NULL)
@@ -629,15 +805,15 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Like
+	 * LIKE
 	 *
-	 * Generates a %LIKE% portion of the query. Separates
-	 * multiple calls with AND
+	 * Generates a %LIKE% portion of the query.
+	 * Separates multiple calls with 'AND'.
 	 *
-	 * @param	mixed
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	mixed	$field
+	 * @param	string	$match
+	 * @param	string	$side
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function like($field, $match = '', $side = 'both', $escape = NULL)
@@ -648,15 +824,15 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Not Like
+	 * NOT LIKE
 	 *
-	 * Generates a NOT LIKE portion of the query. Separates
-	 * multiple calls with AND
+	 * Generates a NOT LIKE portion of the query.
+	 * Separates multiple calls with 'AND'.
 	 *
-	 * @param	mixed
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	mixed	$field
+	 * @param	string	$match
+	 * @param	string	$side
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function not_like($field, $match = '', $side = 'both', $escape = NULL)
@@ -667,15 +843,15 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * OR Like
+	 * OR LIKE
 	 *
-	 * Generates a %LIKE% portion of the query. Separates
-	 * multiple calls with OR
+	 * Generates a %LIKE% portion of the query.
+	 * Separates multiple calls with 'OR'.
 	 *
-	 * @param	mixed
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	mixed	$field
+	 * @param	string	$match
+	 * @param	string	$side
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function or_like($field, $match = '', $side = 'both', $escape = NULL)
@@ -686,15 +862,15 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * OR Not Like
+	 * OR NOT LIKE
 	 *
-	 * Generates a NOT LIKE portion of the query. Separates
-	 * multiple calls with OR
+	 * Generates a NOT LIKE portion of the query.
+	 * Separates multiple calls with 'OR'.
 	 *
-	 * @param	mixed
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	mixed	$field
+	 * @param	string	$match
+	 * @param	string	$side
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function or_not_like($field, $match = '', $side = 'both', $escape = NULL)
@@ -705,16 +881,19 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Like
+	 * Internal LIKE
 	 *
-	 * Called by like(), or_like(), not_like, or_not_like()
+	 * @used-by	like()
+	 * @used-by	or_like()
+	 * @used-by	not_like()
+	 * @used-by	or_not_like()
 	 *
-	 * @param	mixed
-	 * @param	string
-	 * @param	string
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	mixed	$field
+	 * @param	string	$match
+	 * @param	string	$type
+	 * @param	string	$side
+	 * @param	string	$not
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	protected function _like($field, $match = '', $type = 'AND ', $side = 'both', $not = '', $escape = NULL)
@@ -771,8 +950,8 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	/**
 	 * Starts a query group.
 	 *
-	 * @param	string (Internal use only)
-	 * @param	string (Internal use only)
+	 * @param	string	$not	(Internal use only)
+	 * @param	string	$type	(Internal use only)
 	 * @return	object
 	 */
 	public function group_start($not = '', $type = 'AND ')
@@ -860,9 +1039,12 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	/**
 	 * Group_get_type
 	 *
-	 * Called by group_start(), _like(), _where() and _where_in()
+	 * @used-by	group_start()
+	 * @used-by	_like()
+	 * @used-by	_wh()
+	 * @used-by	_where_in()
 	 *
-	 * @param	string
+	 * @param	string	$type
 	 * @return	string
 	 */
 	protected function _group_get_type($type)
@@ -881,8 +1063,8 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	/**
 	 * GROUP BY
 	 *
-	 * @param	string
-	 * @param	bool
+	 * @param	string	$by
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function group_by($by, $escape = NULL)
@@ -919,13 +1101,13 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Sets the HAVING value
+	 * HAVING
 	 *
-	 * Separates multiple calls with AND
+	 * Separates multiple calls with 'AND'.
 	 *
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	string	$key
+	 * @param	string	$value
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function having($key, $value = NULL, $escape = NULL)
@@ -936,13 +1118,13 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Sets the OR HAVING value
+	 * OR HAVING
 	 *
-	 * Separates multiple calls with OR
+	 * Separates multiple calls with 'OR'.
 	 *
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	string	$key
+	 * @param	string	$value
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function or_having($key, $value = NULL, $escape = NULL)
@@ -953,11 +1135,11 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Sets the ORDER BY value
+	 * ORDER BY
 	 *
-	 * @param	string
-	 * @param	string	direction: ASC or DESC
-	 * @param	bool	enable field name escaping
+	 * @param	string	$orderby
+	 * @param	string	$direction	ASC or DESC
+	 * @param	bool	$escape
 	 * @return	object
 	 */
 	public function order_by($orderby, $direction = '', $escape = NULL)
@@ -1009,10 +1191,10 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Sets the LIMIT value
+	 * LIMIT
 	 *
-	 * @param	int	the limit value
-	 * @param	int	the offset value
+	 * @param	int	$value	LIMIT value
+	 * @param	int	$offset	OFFSET value
 	 * @return	object
 	 */
 	public function limit($value, $offset = FALSE)
@@ -1028,7 +1210,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	/**
 	 * Sets the OFFSET value
 	 *
-	 * @param	int	the offset value
+	 * @param	int	$offset	OFFSET value
 	 * @return	object
 	 */
 	public function offset($offset)
@@ -1040,11 +1222,11 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Limit string
+	 * LIMIT string
 	 *
-	 * Generates a platform-specific LIMIT clause
+	 * Generates a platform-specific LIMIT clause.
 	 *
-	 * @param	string	the sql query string
+	 * @param	string	$sql	SQL Query
 	 * @return	string
 	 */
 	protected function _limit($sql)
@@ -1184,10 +1366,10 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	 *
 	 * Allows the where clause, limit and offset to be added directly
 	 *
-	 * @param	string	$table = ''
-	 * @param	string	$where = NULL
-	 * @param	int	$limit = NULL
-	 * @param	int	$offset = NULL
+	 * @param	string	$table
+	 * @param	string	$where
+	 * @param	int	$limit
+	 * @param	int	$offset
 	 * @return	object
 	 */
 	public function get_where($table = '', $where = NULL, $limit = NULL, $offset = NULL)
@@ -1219,9 +1401,9 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	 *
 	 * Compiles batch insert strings and runs the queries
 	 *
-	 * @param	string	$table = ''	table to insert into
-	 * @param	array	$set 		an associative array of insert values
-	 * @return	int	number of rows inserted or FALSE on failure
+	 * @param	string	$table	Table to insert into
+	 * @param	array	$set 	An associative array of insert values
+	 * @return	int	Number of rows inserted or FALSE on failure
 	 */
 	public function insert_batch($table = '', $set = NULL)
 	{
@@ -1540,14 +1722,14 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Update
+	 * UPDATE
 	 *
-	 * Compiles an update string and runs the query
+	 * Compiles an update string and runs the query.
 	 *
-	 * @param	string	$table = ''
-	 * @param	array	$set = NULL	an associative array of update values
-	 * @param	mixed	$where = NULL
-	 * @param	int	$limit = NULL
+	 * @param	string	$table
+	 * @param	array	$set	An associative array of update values
+	 * @param	mixed	$where
+	 * @param	int	$limit
 	 * @return	object
 	 */
 	public function update($table = '', $set = NULL, $where = NULL, $limit = NULL)
@@ -1980,7 +2162,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	 * Generates a query string based on which functions were used.
 	 * Should not be called directly.
 	 *
-	 * @param	bool	$select_override = FALSE
+	 * @param	bool	$select_override
 	 * @return	string
 	 */
 	protected function _compile_select($select_override = FALSE)
@@ -2053,7 +2235,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	 * where(), or_where(), having(), or_having are called prior to from(),
 	 * join() and dbprefix is added only if needed.
 	 *
-	 * @param	string	'qb_where' or 'qb_having'
+	 * @param	string	$qb_key	'qb_where' or 'qb_having'
 	 * @return	string	SQL statement
 	 */
 	protected function _compile_wh($qb_key)
@@ -2291,7 +2473,6 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 			'qb_cache_from'			=> array(),
 			'qb_cache_join'			=> array(),
 			'qb_cache_where'		=> array(),
-			'qb_cache_like'			=> array(),
 			'qb_cache_groupby'		=> array(),
 			'qb_cache_having'		=> array(),
 			'qb_cache_orderby'		=> array(),
@@ -2398,10 +2579,7 @@ abstract class CI_DB_query_builder extends CI_DB_driver {
 	{
 		foreach ($qb_reset_items as $item => $default_value)
 		{
-			if ( ! in_array($item, $this->qb_store_array))
-			{
-				$this->$item = $default_value;
-			}
+			$this->$item = $default_value;
 		}
 	}
 
diff --git a/system/database/DB_result.php b/system/database/DB_result.php
index 704fd7cc2..9d19075ba 100644
--- a/system/database/DB_result.php
+++ b/system/database/DB_result.php
@@ -39,19 +39,68 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 class CI_DB_result {
 
+	/**
+	 * Connection ID
+	 *
+	 * @var	resource|object
+	 */
 	public $conn_id;
+
+	/**
+	 * Result ID
+	 *
+	 * @var	resource|object
+	 */
 	public $result_id;
+
+	/**
+	 * Result Array
+	 *
+	 * @var	array[]
+	 */
 	public $result_array			= array();
+
+	/**
+	 * Result Object
+	 *
+	 * @var	object[]
+	 */
 	public $result_object			= array();
+
+	/**
+	 * Custom Result Object
+	 *
+	 * @var	object[]
+	 */
 	public $custom_result_object		= array();
+
+	/**
+	 * Current Row index
+	 *
+	 * @var	int
+	 */
 	public $current_row			= 0;
+
+	/**
+	 * Number of rows
+	 *
+	 * @var	int
+	 */
 	public $num_rows;
+
+	/**
+	 * Row data
+	 *
+	 * @var	array
+	 */
 	public $row_data;
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Constructor
 	 *
-	 * @param	object
+	 * @param	object	$driver_object
 	 * @return	void
 	 */
 	public function __construct(&$driver_object)
@@ -90,7 +139,7 @@ class CI_DB_result {
 	/**
 	 * Query result. Acts as a wrapper function for the following functions.
 	 *
-	 * @param	string	'object', 'array' or a custom class name
+	 * @param	string	$type	'object', 'array' or a custom class name
 	 * @return	array
 	 */
 	public function result($type = 'object')
@@ -114,8 +163,8 @@ class CI_DB_result {
 	/**
 	 * Custom query result.
 	 *
-	 * @param	string	A string that represents the type of object you want back
-	 * @return	array	of objects
+	 * @param	string	$class_name
+	 * @return	array
 	 */
 	public function custom_result_object($class_name)
 	{
@@ -250,10 +299,12 @@ class CI_DB_result {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Query result.  Acts as a wrapper function for the following functions.
+	 * Row
+	 *
+	 * A wrapper method.
 	 *
-	 * @param	mixed	$n = 0
-	 * @param	string	$type = 'object'	'object' or 'array'
+	 * @param	mixed	$n
+	 * @param	string	$type	'object' or 'array'
 	 * @return	mixed
 	 */
 	public function row($n = 0, $type = 'object')
@@ -340,7 +391,7 @@ class CI_DB_result {
 	/**
 	 * Returns a single result row - object version
 	 *
-	 * @param	int	$n = 0
+	 * @param	int	$n
 	 * @return	object
 	 */
 	public function row_object($n = 0)
@@ -364,7 +415,7 @@ class CI_DB_result {
 	/**
 	 * Returns a single result row - array version
 	 *
-	 * @param	int	$n = 0
+	 * @param	int	$n
 	 * @return	array
 	 */
 	public function row_array($n = 0)
@@ -388,7 +439,7 @@ class CI_DB_result {
 	/**
 	 * Returns the "first" row
 	 *
-	 * @param	string	$type = 'object'
+	 * @param	string	$type
 	 * @return	mixed
 	 */
 	public function first_row($type = 'object')
@@ -402,7 +453,7 @@ class CI_DB_result {
 	/**
 	 * Returns the "last" row
 	 *
-	 * @param	string	$type = 'object'
+	 * @param	string	$type
 	 * @return	mixed
 	 */
 	public function last_row($type = 'object')
@@ -416,7 +467,7 @@ class CI_DB_result {
 	/**
 	 * Returns the "next" row
 	 *
-	 * @param	string	$type = 'object'
+	 * @param	string	$type
 	 * @return	mixed
 	 */
 	public function next_row($type = 'object')
@@ -440,7 +491,7 @@ class CI_DB_result {
 	/**
 	 * Returns the "previous" row
 	 *
-	 * @param	string	$type = 'object'
+	 * @param	string	$type
 	 * @return	mixed
 	 */
 	public function previous_row($type = 'object')
@@ -463,7 +514,7 @@ class CI_DB_result {
 	/**
 	 * Returns an unbuffered row and move pointer to next row
 	 *
-	 * @param	string	$type = 'object'	'array', 'object' or a custom class name
+	 * @param	string	$type	'array', 'object' or a custom class name
 	 * @return	mixed
 	 */
 	public function unbuffered_row($type = 'object')
@@ -483,7 +534,7 @@ class CI_DB_result {
 	// --------------------------------------------------------------------
 
 	/**
-	 * The following functions are normally overloaded by the identically named
+	 * The following methods are normally overloaded by the identically named
 	 * methods in the platform-specific driver -- except when query caching
 	 * is used. When caching is enabled we do not load the other driver.
 	 * These functions are primarily here to prevent undefined function errors
@@ -491,13 +542,118 @@ class CI_DB_result {
 	 * operational due to the unavailability of the database resource IDs with
 	 * cached results.
 	 */
-	public function num_fields() { return 0; }
-	public function list_fields() { return array(); }
-	public function field_data() { return array(); }
-	public function free_result() { $this->result_id = FALSE; }
-	protected function _data_seek() { return FALSE; }
-	protected function _fetch_assoc() { return array(); }
-	protected function _fetch_object() { return array(); }
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Number of fields in the result set
+	 *
+	 * Overriden by driver result classes.
+	 *
+	 * @return	int
+	 */
+	public function num_fields()
+	{
+		return 0;
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Fetch Field Names
+	 *
+	 * Generates an array of column names.
+	 *
+	 * Overriden by driver result classes.
+	 *
+	 * @return	array
+	 */
+	public function list_fields()
+	{
+		return array();
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Field data
+	 *
+	 * Generates an array of objects containing field meta-data.
+	 *
+	 * Overriden by driver result classes.
+	 *
+	 * @return	array
+	 */
+	public function field_data()
+	{
+		return array();
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Free the result
+	 *
+	 * Overriden by driver result classes.
+	 *
+	 * @return	void
+	 */
+	public function free_result()
+	{
+		$this->result_id = FALSE;
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Data Seek
+	 *
+	 * Moves the internal pointer to the desired offset. We call
+	 * this internally before fetching results to make sure the
+	 * result set starts at zero.
+	 *
+	 * Overriden by driver result classes.
+	 *
+	 * @param	int	$n
+	 * @return	bool
+	 */
+	protected function _data_seek($n = 0)
+	{
+		return FALSE;
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Result - associative array
+	 *
+	 * Returns the result set as an array.
+	 *
+	 * Overriden by driver result classes.
+	 *
+	 * @return	array
+	 */
+	protected function _fetch_assoc()
+	{
+		return array();
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Result - object
+	 *
+	 * Returns the result set as an object.
+	 *
+	 * Overriden by driver result classes.
+	 *
+	 * @param	string	$class_name
+	 * @return	object
+	 */
+	protected function _fetch_object($class_name = 'stdClass')
+	{
+		return array();
+	}
 
 }
 
diff --git a/system/database/DB_utility.php b/system/database/DB_utility.php
index 12680be5f..3bd77c84b 100644
--- a/system/database/DB_utility.php
+++ b/system/database/DB_utility.php
@@ -35,13 +35,31 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 abstract class CI_DB_utility extends CI_DB_forge {
 
+	/**
+	 * Database object
+	 *
+	 * @var	object
+	 */
 	public $db;
 
-	// Platform specific SQL strings
-	// Just setting those defaults to FALSE as they are mostly MySQL-specific
+	// --------------------------------------------------------------------
+
+	/**
+	 * OPTIMIZE TABLE statement
+	 *
+	 * @var	string|bool
+	 */
 	protected $_optimize_table	= FALSE;
+
+	/**
+	 * REPAIR TABLE statement
+	 *
+	 * @var	string|bool
+	 */
 	protected $_repair_table	= FALSE;
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Constructor
 	 *
@@ -95,7 +113,7 @@ abstract class CI_DB_utility extends CI_DB_forge {
 	/**
 	 * Determine if a particular database exists
 	 *
-	 * @param	string
+	 * @param	string	$database_name
 	 * @return	bool
 	 */
 	public function database_exists($database_name)
@@ -108,7 +126,7 @@ abstract class CI_DB_utility extends CI_DB_forge {
 	/**
 	 * Optimize Table
 	 *
-	 * @param	string	the table name
+	 * @param	string	$table_name
 	 * @return	mixed
 	 */
 	public function optimize_table($table_name)
@@ -169,7 +187,7 @@ abstract class CI_DB_utility extends CI_DB_forge {
 	/**
 	 * Repair Table
 	 *
-	 * @param	string	the table name
+	 * @param	string	$table_name
 	 * @return	mixed
 	 */
 	public function repair_table($table_name)
@@ -194,10 +212,10 @@ abstract class CI_DB_utility extends CI_DB_forge {
 	/**
 	 * Generate CSV from a query result object
 	 *
-	 * @param	object	The query result object
-	 * @param	string	The delimiter - comma by default
-	 * @param	string	The newline character - \n by default
-	 * @param	string	The enclosure - double quote by default
+	 * @param	object	$query		Query result object
+	 * @param	string	$delim		Delimiter (default: ,)
+	 * @param	string	$newline	Newline character (default: \n)
+	 * @param	string	$enclosure	Enclosure (default: ")
 	 * @return	string
 	 */
 	public function csv_from_result($query, $delim = ',', $newline = "\n", $enclosure = '"')
@@ -234,8 +252,8 @@ abstract class CI_DB_utility extends CI_DB_forge {
 	/**
 	 * Generate XML data from a query result object
 	 *
-	 * @param	object	The query result object
-	 * @param	array	Any preferences
+	 * @param	object	$query	Query result object
+	 * @param	array	$params	Any preferences
 	 * @return	string
 	 */
 	public function xml_from_result($query, $params = array())
@@ -281,7 +299,7 @@ abstract class CI_DB_utility extends CI_DB_forge {
 	/**
 	 * Database Backup
 	 *
-	 * @param	array	$params = array()
+	 * @param	array	$params
 	 * @return	void
 	 */
 	public function backup($params = array())
@@ -294,8 +312,6 @@ abstract class CI_DB_utility extends CI_DB_forge {
 			$params = array('tables' => $params);
 		}
 
-		// ------------------------------------------------------
-
 		// Set up our default preferences
 		$prefs = array(
 				'tables'		=> array(),
-- 
cgit v1.2.3-24-g4f1b