Polish changes following PR #3416

2 files changed, 223 insertions, 206 deletions

diff --git a/system/database/DB_driver.php b/system/database/DB_driver.php
index fdd99167f..9ef197cd1 100644
--- a/system/database/DB_driver.php
+++ b/system/database/DB_driver.php
@@ -456,9 +456,23 @@ abstract class CI_DB_driver {
 	// --------------------------------------------------------------------
 
 	/**
+	 * DB connect
+	 *
+	 * This is just a dummy method that all drivers will override.
+	 *
+	 * @return      mixed
+	 */
+	public function db_connect()
+	{
+		return TRUE;
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
 	 * Persistent database connection
 	 *
-	 * @return	resource
+	 * @return	mixed
 	 */
 	public function db_pconnect()
 	{
@@ -1034,7 +1048,7 @@ abstract class CI_DB_driver {
 	/**
 	 * Escape String
 	 *
-	 * @param	string|string[]	$str
+	 * @param	string|string[]	$str	Input string
 	 * @param	bool	$like	Whether or not the string will be used in a LIKE condition
 	 * @return	string
 	 */
@@ -1102,10 +1116,10 @@ abstract class CI_DB_driver {
 	 * Retrieves the primary key. It assumes that the row in the first
 	 * position is the primary key
 	 *
-	 * @param	string	the table name
-	 * @return	mixed
+	 * @param	string	$table	Table name
+	 * @return	string
 	 */
-	public function primary($table = '')
+	public function primary($table)
 	{
 		$fields = $this->list_fields($table);
 		return is_array($fields) ? current($fields) : FALSE;
@@ -1146,7 +1160,7 @@ abstract class CI_DB_driver {
 	 * Returns an array of table names
 	 *
 	 * @param	string	$constrain_by_prefix = FALSE
-	 * @return	mixed
+	 * @return	array
 	 */
 	public function list_tables($constrain_by_prefix = FALSE)
 	{
@@ -1214,9 +1228,9 @@ abstract class CI_DB_driver {
 	 * Fetch Field Names
 	 *
 	 * @param	string	the table name
-	 * @return	mixed
+	 * @return	array
 	 */
-	public function list_fields($table = '')
+	public function list_fields()
 	{
 		// Is there a cached result?
 		if (isset($this->data_cache['field_names'][$table]))
@@ -1224,11 +1238,6 @@ abstract class CI_DB_driver {
 			return $this->data_cache['field_names'][$table];
 		}
 
-		if ($table === '')
-		{
-			return ($this->db_debug) ? $this->display_error('db_field_param_missing') : FALSE;
-		}
-
 		if (FALSE === ($sql = $this->_list_columns($table)))
 		{
 			return ($this->db_debug) ? $this->display_error('db_unsupported_function') : FALSE;
@@ -1282,18 +1291,13 @@ abstract class CI_DB_driver {
 	/**
 	 * Returns an object with field data
 	 *
-	 * @param	string	the table name
-	 * @return	object
+	 * @param	string	$table	the table name
+	 * @return	array
 	 */
-	public function field_data($table = '')
+	public function field_data($table)
 	{
-		if ($table === '')
-		{
-			return ($this->db_debug) ? $this->display_error('db_field_param_missing') : FALSE;
-		}
-
 		$query = $this->query($this->_field_data($this->protect_identifiers($table, TRUE, NULL, FALSE)));
-		return $query->field_data();
+		return ($query) ? $query->field_data() : FALSE;
 	}
 
 	// --------------------------------------------------------------------
diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst
index 872077a7e..7bee555c8 100644
--- a/user_guide_src/source/database/db_driver_reference.rst
+++ b/user_guide_src/source/database/db_driver_reference.rst
@@ -9,129 +9,140 @@ class for the specific database will extend and instantiate it.
 The how-to material for this has been split over several articles.
 This article is intended to be a reference for them.
 
+.. important:: Not all methods are supported by all database drivers,
+	some of them may fail (and return FALSE) if the underlying
+	driver does not support them.
+
 .. class:: CI_DB_driver
 
 	.. method:: initialize()
 
 		:returns:	TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:rtype:	bool
+
+		Initialize database settings, establish a connection to
+		the database.
+
+	.. method:: db_connect($persistent = TRUE)
+
+		:param	bool	$persistent: Whether to establish a persistent connection or a regular one
+		:returns:	Database connection resource/object or FALSE on failure
+		:rtype:	mixed
+
+		Establish a connection with the database.
 
-		Initialize Database Settings; 
-                establish a connection to the database.
+		.. note:: The returned value depends on the underlying
+			driver in use. For example, a ``mysqli`` instance
+			will be returned with the 'mysqli' driver.
 
 	.. method:: db_pconnect()
 
-		:returns:	TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:returns:	Database connection resource/object or FALSE on failure
+		:rtype:	mixed
+
+		Establish a persistent connection with the database.
 
-		Establish a persistent database connection
+		.. note:: This method is just an alias for ``db_connect(TRUE)``.
 
 	.. method:: reconnect()
 
 		:returns:	TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:rtype:	bool
 
-		Keep / reestablish the db connection if no queries have been
-                sent for a length of time exceeding the server's idle timeout.
+		Keep / reestablish the database connection if no queries
+		have been sent for a length of time exceeding the
+		server's idle timeout.
 
-                This is only available in drivers that support it.
-
-	.. method:: db_select()
+	.. method:: db_select([$database = ''])
 
+		:param	string	$database: Database name
 		:returns:	TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:rtype:	bool
 
-		Select database
+		Select / switch the current database.
 
 	.. method:: db_set_charset($charset)
 
 		:param	string	$charset: Character set name
 		:returns:	TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:rtype:	bool
 
-		Set client character set
+		Set client character set.
 
 	.. method:: platform()
 
 		:returns:	Platform name
 		:rtype:	string
 
-		The name of the platform in use (mysql, mssql, etc...)
+		The name of the platform in use (mysql, mssql, etc...).
 
 	.. method:: version()
 
-		:returns:	The version of the database being used.
+		:returns:	The version of the database being used
 		:rtype:	string
 
-		Database version number
+		Database version number.
 
 	.. method:: query($sql[, $binds = FALSE[, $return_object = NULL]]])
 
 		:param	string	$sql: The SQL statement to execute
 		:param	array	$binds: An array of binding data
-		:param	bool	$return_object: Character set name
-		:returns:	True on "update" success, DB_result object on "query" success, FALSE on failure
+		:param	bool	$return_object: Whether to return a result object or not
+		:returns:	TRUE for successful "write-type" queries, CI_DB_result instance (method chaining) on "query" success, FALSE on failure
 		:rtype:	mixed
 
-		Execute the query
+		Execute an SQL query.
 
-                Accepts an SQL string as input and returns a result object 
-                upon
-                successful execution of a "read" type query. Returns boolean 
-                TRUE
-                upon successful execution of a "write" type query. 
-                Returns boolean
-                FALSE upon failure, and if the $db_debug variable is set 
-                to TRUE
-                will raise an error.
+		Accepts an SQL string as input and returns a result object
+		upon successful execution of a "read" type query.
 
-	.. method:: load_rdriver()
+		Returns:
 
-		:returns:	The DB_result object appropriate for the driver in use
-		:rtype:	DB_result
+		   - Boolean TRUE upon successful execution of a "write type" queries
+		   - Boolean FALSE upon failure
+		   - ``CI_DB_result`` object for "read type" queries
 
-		Load the result drivers
+		.. note: If 'db_debug' setting is set to TRUE, an error
+			page will be displayed instead of returning FALSE
+			on failures and script execution will stop.
 
 	.. method:: simple_query($sql)
 
 		:param	string	$sql: The SQL statement to execute
-		:returns:	True on "update" success, DB_result object on "query" success, FALSE on failure
+		:returns:	Whatever the underlying driver's "query" function returns
 		:rtype:	mixed
 
-		Simple Query
-
-                This is a simplified version of the query() function. Internally
-                we only use it when running transaction commands since they do
-                not require all the features of the main query() function.
+		A simplified version of the ``query()`` method, appropriate
+		for use when you don't need to get a result object or to
+		just send a query to the database and not care for the result.
 
-	.. method:: trans_off()
+	.. method:: trans_strict([$mode = TRUE])
 
+		:param	bool	$mode: Strict mode flag
 		:rtype:	void
 
-		Disable Transactions.
+		Enable/disable transaction "strict" mode.
 
-                This permits transactions to be disabled at run-time.
+		When strict mode is enabled, if you are running multiple
+		groups of transactions and one group fails, all groups
+		will be rolled back.
 
-	.. method:: trans_strict([$mode = TRUE])
+		If strict mode is disabled, each group is treated
+		autonomously, meaning a failure of one group will not
+		affect any others.
 
-		:param	boolean	$mode: TRUE for strict mode
-		:rtype:	void
+	.. method:: trans_off()
 
-		Enable/disable Transaction Strict Mode.
+		:rtype:	void
 
-                When strict mode is enabled, if you are running multiple 
-                groups of
-                transactions, if one group fails all groups will be rolled back.
-                If strict mode is disabled, each group is treated autonomously, 
-                meaning
-                a failure of one group will not affect any others.
+		Disables transactions at run-time.
 
-	.. method:: trans_start([$test_mode = FALSE[)
+	.. method:: trans_start([$test_mode = FALSE])
 
-		:param	boolean	$test_mode: TRUE for testing mode
+		:param	bool	$test_mode: Test mode flag
 		:rtype:	void
 
-		Start Transaction.
+		Start a transaction.
 
 	.. method:: trans_complete()
 
@@ -141,11 +152,11 @@ This article is intended to be a reference for them.
 
 	.. method:: trans_status()
 
-                :returns:   TRUE if the transaction succeeded, FALSE if it failed
-		:rtype:	boolean
+                :returns:	TRUE if the transaction succeeded, FALSE if it failed
+		:rtype:	bool
 
-		Lets you retrieve the transaction flag to determine if it
-                has failed.
+		Lets you retrieve the transaction status flag to
+		determine if it has failed.
 
 	.. method:: compile_binds($sql, $binds)
 
@@ -154,15 +165,16 @@ This article is intended to be a reference for them.
 		:returns:	The updated SQL statement
 		:rtype:	string
 
-		Compile Bindings
+		Compiles an SQL query with the bind values passed for it.
 
 	.. method:: is_write_type($sql)
 
 		:param	string	$sql: The SQL statement 
-		:returns:	TRUE if the SQL statement is a "write" type of statement
-		:rtype:	boolean
+		:returns:	TRUE if the SQL statement is of "write type", FALSE if not
+		:rtype:	bool
 
-		Determines if a query is a "write" type.
+		Determines if a query is of a "write" type (such as
+		INSERT, UPDATE, DELETE) or "read" type (i.e. SELECT).
 
 	.. method:: elapsed_time([$decimals = 6])
 
@@ -174,10 +186,11 @@ This article is intended to be a reference for them.
 
 	.. method:: total_queries()
 
-		:returns:	The total number of queries
+		:returns:	The total number of queries executed
 		:rtype:	int
 
-		Returns the total number of queries.
+		Returns the total number of queries that have been
+		executed so far.
 
 	.. method:: last_query()
 
@@ -188,220 +201,220 @@ This article is intended to be a reference for them.
 
 	.. method:: escape($str)
 
-		:param	string	$str: The string to work with
-		:returns:	The escaped string
+		:param	mixed	$str: The value to escape, or an array of multiple ones
+		:returns:	The escaped value(s)
 		:rtype:	mixed
 
-		"Smart" Escape String.
-
-                Escapes data based on type.
-                Sets boolean and null types
+		Escapes input data based on type, including boolean and
+		NULLs.
 
 	.. method:: escape_str($str[, $like = FALSE])
 
-		:param	mixed	$str: The string or array of strings to work with
-                :param	boolean	$like: Whether or not the string will be used in a LIKE condition
+		:param	mixed	$str: A string value or array of multiple ones
+		:param	bool	$like: Whether or not the string will be used in a LIKE condition
 		:returns:	The escaped string(s)
 		:rtype:	mixed
 
-		Escape String.
+		Escapes string values.
+
+		.. warning:: The returned strings do NOT include quotes
+			around them.
 
 	.. method:: escape_like_str($str)
 
-		:param	mixed	$str: The string or array of strings to work with
-                :returns:	The escaped string(s)
+		:param	mixed	$str: A string value or array of multiple ones
+		:returns:	The escaped string(s)
 		:rtype:	mixed
 
-		Escape LIKE String.
-                
-                Calls the individual driver for platform
-                specific escaping for LIKE conditions.
+		Escape LIKE strings.
 
-	.. method:: primary([$table = ''])
+		Similar to ``escape_str()``, but will also escape the ``%``
+		and ``_`` wildcard characters, so that they don't cause
+		false-positives in LIKE conditions.
 
-		:param	string	$table: The table name
-                :returns:	The primary key name, FALSE if none
-		:rtype:	mixed
+	.. method:: primary($table)
 
-		Primary.
-                
-                Retrieves the primary key. It assumes that the row in the first
-                position is the primary key.
+		:param	string	$table: Table name
+		:returns:	The primary key name, FALSE if none
+		:rtype:	string
+
+		Retrieves the primary key of a table.
+
+		.. note:: If the database platform does not support primary
+			key detection, the first column name may be assumed
+			as the primary key.
 
 	.. method:: count_all([$table = ''])
 
-		:param	string	$table: The table name
-                :returns:	Record count for specified table
+		:param	string	$table: Table name
+		:returns:	Row count for the specified table
 		:rtype:	int
 
-		"Count All" query.
-                
-                Generates a platform-specific query string that counts 
-                all records in
-                the specified database.
+		Returns the total number of rows in a table, or 0 if no
+		table was provided.
 
 	.. method:: list_tables([$constrain_by_prefix = FALSE])
 
-		:param	boolean	$constrain_by_prefix: TRUE to constrain the tables considered
-                :returns:	Array of table names, FALSE if the operation is unsupported
-		:rtype:	mixed
+		:param	bool	$constrain_by_prefix: TRUE to match table names by the configured dbprefix
+		:returns:	Array of table names or FALSE on failure
+		:rtype:	array
 
-		Returns an array of table names.
+		Gets a list of the tables in the current database.
 
 	.. method:: table_exists($table_name)
 
 		:param	string	$table_name: The table name
-                :returns:	TRUE if that table exists
-		:rtype:	boolean
+		:returns:	TRUE if that table exists, FALSE if not
+		:rtype:	bool
 
 		Determine if a particular table exists.
 
-	.. method:: list_fields([$table = ''])
+	.. method:: list_fields($table)
 
 		:param	string	$table: The table name
-                :returns:	Array of field names, FALSE if the table doesn't exist or the operation is un-supported
-		:rtype:	mixed
+		:returns:	Array of field names or FALSE on failure
+		:rtype:	array
 
-		Fetch Field Names.
+		Gets a list of the field names in a table.
 
 	.. method:: field_exists($field_name, $table_name)
 
 		:param	string	$table_name: The table name
-                :param	string	$field_name: The field name
-                :returns:	TRUE if that field exists in that table
-		:rtype:	boolean
+		:param	string	$field_name: The field name
+		:returns:	TRUE if that field exists in that table, FALSE if not
+		:rtype:	bool
 
 		Determine if a particular field exists.
 
-	.. method:: field_data([$table = ''])
+	.. method:: field_data($table)
 
 		:param	string	$table: The table name
-                :returns:	Object with field data, FALSE if no table given
-		:rtype:	mixed
+		:returns:	Array of field data items or FALSE on failure
+		:rtype:	array
 
-		Returns an object with field data.
+		Gets a list containing field data about a table.
 
 	.. method:: escape_identifiers($item)
 
 		:param	mixed	$item: The item or array of items to escape
-                :returns:	The item(s), escaped
+		:returns:	The input item(s), escaped
 		:rtype:	mixed
 
-		Escape the SQL Identifiers.
-                
-                This function escapes column and table names
+		Escape SQL identifiers, such as column, table and names.
 
 	.. method:: insert_string($table, $data)
 
-		:param	string	$table: The table upon which the query will be performed
-                :param	array	$data: an associative array of data key/values
-                :returns:	The SQL insert string
+		:param	string	$table: The target table
+		:param	array	$data: An associative array of key/value pairs
+		:returns:	The SQL INSERT statement, as a string
 		:rtype:	string
 
-		Generate an insert string.
+		Generate an INSERT statement string.
 
 	.. method:: update_string($table, $data, $where)
 
-		:param	string	$table: The table upon which the query will be performed
-                :param	array	$data: an associative array of data key/values
-                :param	mixed	$where: the "where" statement
-                :returns:	The SQL update string
+		:param	string	$table: The target table
+		:param	array	$data: An associative array of key/value pairs
+		:param	mixed	$where: The WHERE statement conditions
+		:returns:	The SQL UPDATE statement, as a string
 		:rtype:	string
 
-		Generate an update string.
+		Generate an UPDATE statement string.
 
 	.. method:: call_function($function)
 
 		:param	string	$function: Function name
-                :returns:	The function result
+		:returns:	The function result
 		:rtype:	string
 
-		Enables a native PHP function to be run, using a platform 
-                agnostic wrapper.
+		Runs a native PHP function , using a platform agnostic
+		wrapper.
 
 	.. method:: cache_set_path([$path = ''])
 
-		:param	string	$path: the path to the cache directory
-                :rtype:	void
+		:param	string	$path: Path to the cache directory
+		:rtype:	void
 
-		Set Cache Directory Path.
+		Sets the directory path to use for caching storage.
 
 	.. method:: cache_on()
 
-                :returns:	cache_on value
-                :rtype:	boolean
+		:returns:	TRUE if caching is on, FALSE if not
+		:rtype:	bool
 
-		Enable Query Caching.
+		Enable database results caching.
 
 	.. method:: cache_off()
 
-                :returns:	cache_on value
-                :rtype:	boolean
+		:returns:	TRUE if caching is on, FALSE if not
+		:rtype:	bool
 
-		Disable Query Caching.
+		Disable database results caching.
 
 	.. method:: cache_delete([$segment_one = ''[, $segment_two = '']])
 
-                :param	string	$segment_one: first URI segment
-                :param	string	$segment_two: second URI segment
-                :returns:	TRUE on success, FALSE on failure
-                :rtype:	boolean
+		:param	string	$segment_one: First URI segment
+		:param	string	$segment_two: Second URI segment
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-		Delete the cache files associated with a particular URI
+		Delete the cache files associated with a particular URI.
 
 	.. method:: cache_delete_all()
 
-                :returns:	TRUE on success, FALSE on failure
-                :rtype:	boolean
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-		Delete All cache files
+		Delete all cache files.
 
 	.. method:: close()
 
-                :rtype:	void
+		:rtype:	void
 
-		Close DB Connection
+		Close the DB Connection.
 
 	.. method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]])
 
-                :param	string	$error: the error message
-                :param	string	$swap: any "swap" values
-                :param	boolean	$native: whether to localize the message
-                :returns:   sends the application/views/errors/error_db.php template
+		:param	string	$error: The error message
+		:param	string	$swap: Any "swap" values
+		:param	bool	$native: Whether to localize the message
+		:rtype:	void
+
+		:returns:	Displays the DB error screensends the application/views/errors/error_db.php template
                 :rtype:	string
 
-		Display an error message
+		Display an error message and stop script execution.
+
+		The message is displayed using the
+		*application/views/errors/error_db.php* template.
 
 	.. method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]])
 
-                :param	string	$item: the item
-                :param	boolean	$prefix_single: whether to use a single prefix
-                :param	boolean	$protect_identifiers: whether to protect identifiers
-                :param	boolean	$field_exists: whether the supplied item does not contain a field name.
-                :returns:   the modified item
-                :rtype:	string
+		:param	string	$item: The item to work with
+		:param	bool	$prefix_single: Whether to apply the dbprefix even if the input item is a single identifier
+		:param	bool	$protect_identifiers: Whether to quote identifiers
+		:param	bool	$field_exists: Whether the supplied item contains a field name or not
+		:returns:	The modified item
+		:rtype:	string
+
+		Takes a column or table name (optionally with an alias)
+		and applies the configured *dbprefix* to it.
+
+		Some logic is necessary in order to deal with
+		column names that include the path. 
+
+		Consider a query like this::
+
+			SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table
+
+		Or a query with aliasing::
+
+			SELECT m.member_id, m.member_name FROM members AS m
+
+		Since the column name can include up to four segments
+		(host, DB, table, column) or also have an alias prefix,
+		we need to do a bit of work to figure this out and
+		insert the table prefix (if it exists) in the proper
+		position, and escape only the correct identifiers.
 
-		Protect Identifiers.
-                
-                This function is used extensively by the Query Builder class, 
-                and by
-                a couple functions in this class.
-                It takes a column or table name (optionally with an alias) 
-                and inserts
-                the table prefix onto it. Some logic is necessary in order 
-                to deal with
-                column names that include the path. Consider a query like this::
-                
-                        SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table
-                
-                Or a query with aliasing::
-                
-                        SELECT m.member_id, m.member_name FROM members AS m
-                
-                Since the column name can include up to four segments 
-                (host, DB, table, column)
-                or also have an alias prefix, we need to do a bit of work 
-                to figure this out and
-                insert the table prefix (if it exists) in the proper position, 
-                and escape only
-                the correct identifiers.
\ No newline at end of file
+		This method is used extensively by the Query Builder class.
\ No newline at end of file