[ci skip] Update DB result docs

Related: #3395

1 files changed, 143 insertions, 133 deletions

diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst
index 044360ebb..ae81998c7 100644
--- a/user_guide_src/source/database/results.rst
+++ b/user_guide_src/source/database/results.rst
@@ -12,8 +12,7 @@ There are several ways to generate query results:
 Result Arrays
 *************
 
-result()
-========
+**result()**
 
 This method returns the query result as an array of **objects**, or
 **an empty array** on failure. Typically you'll use this in a foreach
@@ -28,7 +27,7 @@ loop, like this::
 		echo $row->body;
 	}
 
-The above method is an alias of result_object().
+The above method is an alias of ``result_object()``.
 
 If you run queries that might **not** produce a result, you are
 encouraged to test the result first::
@@ -54,12 +53,11 @@ instantiate for each result object (note: this class must be loaded)
 
 	foreach ($query->result('User') as $user)
 	{
-	   echo $user->name; // call attributes
-	   echo $user->reverse_name(); // or methods defined on the 'User' class
+		echo $user->name; // access attributes
+		echo $user->reverse_name(); // or methods defined on the 'User' class
 	}
 
-result_array()
-===============
+**result_array()**
 
 This method returns the query result as a pure array, or an empty
 array when no result is produced. Typically you'll use this in a foreach
@@ -78,8 +76,7 @@ loop, like this::
 Result Rows
 ***********
 
-row()
-=====
+**row()**
 
 This method returns a single result row. If your query has more than
 one row, it returns only the first row. The result is returned as an
@@ -107,13 +104,12 @@ to instantiate the row with::
 	$query = $this->db->query("SELECT * FROM users LIMIT 1;");
 	$query->row(0, 'User');
 	
-	echo $row->name; // call attributes
+	echo $row->name; // access attributes
 	echo $row->reverse_name(); // or methods defined on the 'User' class
 
-row_array()
-===========
+**row_array()**
 
-Identical to the above row() method, except it returns an array.
+Identical to the above ``row()`` method, except it returns an array.
 Example::
 
 	$query = $this->db->query("YOUR QUERY");
@@ -148,11 +144,11 @@ parameter:
 	| **$row = $query->next_row('array')**
 	| **$row = $query->previous_row('array')**
 
-.. note:: all the methods above will load the whole result into memory 
-    (prefetching) use unbuffered_row() for processing large result sets.
+.. note:: All the methods above will load the whole result into memory
+	(prefetching). Use ``unbuffered_row()`` for processing large
+	result sets.
 
-unbuffered_row()
-================
+**unbuffered_row()**
 
 This method returns a single result row without prefetching the whole
 result in memory as ``row()`` does. If your query has more than one row,
@@ -180,7 +176,7 @@ the returned value's type::
 Result Helper Methods
 *********************
 
-**$query->num_rows()**
+**num_rows()**
 
 The number of rows returned by the query. Note: In this example, $query
 is the variable that the query result object is assigned to::
@@ -189,13 +185,12 @@ is the variable that the query result object is assigned to::
 	
 	echo $query->num_rows();
 
-.. note::
-	Not all database drivers have a native way of getting the total
+.. note:: Not all database drivers have a native way of getting the total
 	number of rows for a result set. When this is the case, all of
-	the data is prefetched and count() is manually called on the
-	resulting array in order to achieve the same methodality.
+	the data is prefetched and ``count()`` is manually called on the
+	resulting array in order to achieve the same result.
 	
-**$query->num_fields()**
+**num_fields()**
 
 The number of FIELDS (columns) returned by the query. Make sure to call
 the method using your query result object::
@@ -204,13 +199,14 @@ the method using your query result object::
 	
 	echo $query->num_fields();
 
-**$query->free_result()**
+**free_result()**
 
 It frees the memory associated with the result and deletes the result
 resource ID. Normally PHP frees its memory automatically at the end of
 script execution. However, if you are running a lot of queries in a
 particular script you might want to free the result after each query
-result has been generated in order to cut down on memory consumptions.
+result has been generated in order to cut down on memory consumption.
+
 Example::
 
 	$query = $this->db->query('SELECT title FROM my_table');
@@ -219,6 +215,7 @@ Example::
 	{
 		echo $row->title;
 	}
+
 	$query->free_result();  // The $query result object will no longer be available
 
 	$query2 = $this->db->query('SELECT name FROM some_table');
@@ -250,175 +247,188 @@ Class Reference
 
 .. class:: CI_DB_result
 
-	.. method:: custom_result_object($class_name)
-
-		:param	string	$class_name: Class name for the results
-		:returns:	Array of objects of type $class_name
-		:rtype:	array of $class_name
+	.. method:: result([$type = 'object'])
 
-		Return the query results as an array of the specified class.
+		:param	string	$type: Type of requested results - array, object, or class name
+		:returns:	Array containing the fetched rows
+		:rtype:	array
 
-	.. method:: custom_row_object($n, $type)
+		A wrapper for the ``result_array()``, ``result_object()``
+		and ``custom_result_object()`` methods.
 
-		:param	int	$n: Index of the results row to return
-		:param	string	$class_name: Class name for the results
-		:returns:	Object of type $type
-		:rtype:	$type
+		Usage: see `Result Arrays`_.
 
-		Return a specific row from the query results as an object of 
-                the specified class.
+	.. method:: result_array()
 
-	.. method:: data_seek([$n = 0])
+		:returns:	Array containing the fetched rows
+		:rtype:	array
 
-		:param	int	$n: Index of the results row to be returned next
-		:returns:	TRUE on success, FALSE otherwise
-		:rtype:	bool
+		Returns the query results as an array of rows, where each
+		row is itself an associative array.
 
-		Moves the internal results row pointer to the desired offset.
-                Usage: see `Result Helper Methods`_.
+		Usage: see `Result Arrays`_.
 
-	.. method:: field_data()
+	.. method:: result_object()
 
-		:returns:	Array of objects containing field meta-data.
+		:returns:	Array containing the fetched rows
 		:rtype:	array
 
-		Generates an array of objects containing field meta-data.
+		Returns the query results as an array of rows, where each
+		row is an object of type ``stdClass``.
 
-	.. method:: first_row([$type = 'object'])
+		Usage: see `Result Arrays`_.
 
-		:param	string	$type: Type of result requested - array, object, or class name
-		:returns:	First row of result set
-		:rtype:	mixed
+	.. method:: custom_result_object($class_name)
 
-		Returns the "first" row, as an array, generic object, or 
-                object of a specific class
+		:param	string	$class_name: Class name for the resulting rows
+		:returns:	Array containing the fetched rows
+		:rtype:	array
 
-	.. method:: free_result()
+		Returns the query results as an array of rows, where each
+		row is an instance of the specified class.
 
-		:rtype:	void
+	.. method:: row([$n = 0[, $type = 'object']])
 
-		Free the result.
-                Usage: see `Result Helper Methods`_.
+		:param	int	$n: Index of the query results row to be returned
+		:param	string	$type: Type of the requested result - array, object, or class name
+		:returns:	The requested row or NULL if it doesn't exist
+		:rtype:	mixed
 
-	.. method:: last_row([$type = 'object'])
+		A wrapper for the ``row_array()``, ``row_object() and 
+		``custom_row_object()`` methods.
+
+		Usage: see `Result Rows`_.
 
-		:param	string	$type: Type of result requested - array, object, or class name
-		:returns:	Last row of result set
+	.. method:: unbuffered_row([$type = 'object'])
+
+		:param	string	$type: Type of the requested result - array, object, or class name
+		:returns:	Next row from the result set or NULL if it doesn't exist
 		:rtype:	mixed
 
-		Returns the "last" row, as an array, generic object, or 
-                object of a specific class
+		Fetches the next result row and returns it in the
+		requested form.
 
-	.. method:: list_fields()
+		Usage: see `Result Rows`_.
 
-		:returns:	Array of column names
+	.. method:: row_array([$n = 0])
+
+		:param	int	$n: Index of the query results row to be returned
+		:returns:	The requested row or NULL if it doesn't exist
 		:rtype:	array
 
-		Fetch Field Names
+		Returns the requested result row as an associative array.
 
-	.. method:: next_row([$type = 'object'])
+		Usage: see `Result Rows`_.
 
-		:param	string	$type: Type of result requested - array, object, or class name
-		:returns:	"Next" row of result set, NULL if there isn't one
-		:rtype:	mixed
+	.. method:: row_object([$n = 0])
 
-		Returns the "next" row, as an array, generic object, or 
-                object of a specific class
+		:param	int	$n: Index of the query results row to be returned
+                :returns:	The requested row or NULL if it doesn't exist
+		:rtype:	stdClass
 
-	.. method:: num_fields()
+		Returns the requested result row as an object of type
+		``stdClass``.
 
-		:returns:	Number of fields in the result set
-		:rtype:	integer
+		Usage: see `Result Rows`_.
 
-		Number of fields in the result set.
-                Usage: see `Result Helper Methods`_.
+	.. method:: custom_row_object($n, $type)
 
-	.. method:: num_rows()
+		:param	int	$n: Index of the results row to return
+		:param	string	$class_name: Class name for the resulting row
+		:returns:	The requested row or NULL if it doesn't exist
+		:rtype:	$type
 
-		:returns:	Number of rows in the result set
-		:rtype:	integer
+		Returns the requested result row as an instance of the
+		requested class.
 
-		Number of rows in the result set.
-                Usage: see `Result Helper Methods`_.
+	.. method:: data_seek([$n = 0])
 
-	.. method:: previous_row([$type = 'object'])
+		:param	int	$n: Index of the results row to be returned next
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-		:param	string	$type: Type of result requested - array, object, or class name
-		:returns:	"Previous" row of result set, NULL if there isn't one
-		:rtype:	mixed
+		Moves the internal results row pointer to the desired offset.
 
-		Returns the "previous" row, as an array, generic object, or 
-                object of a specific class
+		Usage: see `Result Helper Methods`_.
 
-	.. method:: result([$type = 'object'])
+	.. method:: set_row($key[, $value = NULL])
+
+		:param	mixed	$key: Column name or array of key/value pairs
+		:param	mixed	$value: Value to assign to the column, $key is a single field name
+		:rtype:	void
+
+		Assigns a value to a particular column.
+
+	.. method:: next_row([$type = 'object'])
 
-		:param	string	$type: Type of result requested - array, object, or class name
-		:returns:	Query results as the specified type
+		:param	string	$type: Type of the requested result - array, object, or class name
+		:returns:	Next row of result set, or NULL if it doesn't exist
 		:rtype:	mixed
 
-		Query result. Acts as a wrapper function for the result_array, 
-                result_object and custom_result_object methods.
-                Usage: see `Result Arrays`_.
+		Returns the next row from the result set.
 
-	.. method:: result_array()
+	.. method:: previous_row([$type = 'object'])
 
-		:returns:	Query results as an associative array
-		:rtype:	array
+		:param	string	$type: Type of the requested result - array, object, or class name
+		:returns:	Previous row of result set, or NULL if it doesn't exist
+		:rtype:	mixed
 
-		Returns the query results as an array of rows, where each
-                row is itself an associative array.
-                Usage: see `Result Arrays`_.
+		Returns the previous row from the result set.
 
-	.. method:: result_object()
+	.. method:: first_row([$type = 'object'])
 
-		:returns:	Query results as an array of objects
-		:rtype:	array
+		:param	string	$type: Type of the requested result - array, object, or class name
+		:returns:	First row of result set, or NULL if it doesn't exist
+		:rtype:	mixed
 
-		Returns the query results as an array of rows, where each
-                row is an object
+		Returns the first row from the result set.
 
-	.. method:: row([$n = 0[, $type = 'object']])
+	.. method:: last_row([$type = 'object'])
 
-		:param	integer	$n: Index of the query results row to be returned
-                :param	string	$type: Type of result requested - array, object, or class name
-		:returns:	Requested row of result set
+		:param	string	$type: Type of the requested result - array, object, or class name
+		:returns:	Last row of result set, or NULL if it doesn't exist
 		:rtype:	mixed
 
-		Wrapper for result_row_array, result_row_object, and 
-                custom_row_object.
-                Usage: see `Result Rows`_.
+		Returns the last row from the result set.
 
-	.. method:: row_array([$n = 0])
+	.. method:: num_rows()
 
-		:param	integer	$n: Index of the query results row to be returned
-                :returns:	Requested row of result set
-		:rtype:	array
+		:returns:	Number of rows in the result set
+		:rtype:	int
 
-		Returns requested result row as an associative array.
-                Usage: see `Result Rows`_.
+		Returns the number of rows in the result set.
 
-	.. method:: row_object([$n = 0])
+		Usage: see `Result Helper Methods`_.
 
-		:param	integer	$n: Index of the query results row to be returned
-                :returns:	Requested row of result set
-		:rtype:	object
+	.. method:: num_fields()
 
-		Returns requested result row as an object
+		:returns:	Number of fields in the result set
+		:rtype:	int
 
-	.. method:: set_row($key[, $value = NULL])
+		Returns the number of fields in the result set.
+
+		Usage: see `Result Helper Methods`_.
+
+	.. method:: field_data()
+
+		:returns:	Array containing field meta-data
+		:rtype:	array
+
+		Generates an array of ``stdClass`` objects containing
+		field meta-data.
+
+	.. method:: free_result()
 
-		:param	mixed	$key: Column index or array of key/value pairs
-                :param	mixed	$value: Result to assign to a column if the key is an index
 		:rtype:	void
 
-		Assigns an item into a particular column slot
+		Frees a result set.
 
-	.. method:: unbuffered_row([$type = 'object'])
+		Usage: see `Result Helper Methods`_.
 
-		:param	string	$type: Type of result requested - array, object, or class name
-		:returns:	Requested row of result set
-		:rtype:	mixed
+	.. method:: list_fields()
+
+		:returns:	Array of column names
+		:rtype:	array
 
-		Fetches the next result row and returns it in the requested 
-                form.
-                Usage: see `Result Rows`_.
\ No newline at end of file
+		Returns an array containing the field names in the
+		result set.
\ No newline at end of file