DB forge/utilities polishing (docs) following #3375, #3378

3 files changed, 89 insertions, 98 deletions

diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst
index 371397d26..59a6591b7 100644
--- a/user_guide_src/source/database/forge.rst
+++ b/user_guide_src/source/database/forge.rst
@@ -185,7 +185,6 @@ below is for MySQL.
 	// gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`)
 
 
-
 Creating a table
 ================
 
@@ -242,7 +241,6 @@ Executes a TABLE rename
 	// gives ALTER TABLE old_table_name RENAME TO new_table_name
 
 
-
 ****************
 Modifying Tables
 ****************
@@ -318,104 +316,93 @@ change the name you can add a "name" key into the field defining array.
 Class Reference
 ***************
 
-.. class:: DB_forge
-
-	.. method:: __construct(&$db)
-
-		:param	object	$db: Database object
-		:returns:	DB_forge object for the specified database
-		:rtype:	DB_forge
-
-		Initializes a database forge.
+.. class:: CI_DB_forge
 
-	.. method:: add_column($table = '', $field = array(), $_after = NULL)
+	.. method:: add_column($table[, $field = array()[, $_after = NULL]])
 
-		:param	string	$table: Table name
-		:param	array	$field: Column definitions
+		:param	string	$table: Table name to add the column to
+		:param	array	$field: Column definition(s)
 		:param	string	$_after: Column for AFTER clause (deprecated)
-                :returns:   TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-                Add a column to a table. Usage:  See `Adding a Column to a Table`_.
+		Adds a column to a table. Usage:  See `Adding a Column to a Table`_.
 
-	.. method:: add_field($field = '')
+	.. method:: add_field($field)
 
-		:param	array	$field: Field to add
-                :returns:   DB_forge instance
-		:rtype:	object
+		:param	array	$field: Field definition to add
+		:returns:	CI_DB_forge instance (method chaining)
+		:rtype:	CI_DB_forge
 
-                Add a field to the set that will be used to create a table. Usage:  See `Adding fields`_.
+                Adds a field to the set that will be used to create a table. Usage:  See `Adding fields`_.
 
-	.. method:: add_key($key = '', $primary = FALSE)
+	.. method:: add_key($key[, $primary = FALSE])
 
 		:param	array	$key: Name of a key field
-                :param  boolean $primary:   TRUE if this key is to be a primary key
-                :returns:   DB_forge instance
-		:rtype:	object
+		:param	bool	$primary: Set to TRUE if it should be a primary key or a regular one
+		:returns:	CI_DB_forge instance (method chaining)
+		:rtype:	CI_DB_forge
 
-                Specify a key field to be used to create a table. Usage:  See `Adding Keys`_.
+		Adds a key to the set that will be used to create a table. Usage:  See `Adding Keys`_.
 
 	.. method:: create_database($db_name)
 
 		:param	string	$db_name: Name of the database to create
-                :returns:   TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-                Create a new database. Usage:  See `Creating and Dropping Databases`_.
+		Creates a new database. Usage:  See `Creating and Dropping Databases`_.
 
-	.. method:: create_table($table = '', $if_not_exists = FALSE, array $attributes = array())
+	.. method:: create_table($table[, $if_not_exists = FALSE[, array $attributes = array()]])
 
 		:param	string	$table: Name of the table to create
-		:param	string	$if_not_exists: TRUE to add an 'IF NOT EXISTS' clause
-		:param	string	$attributes: Associative array of table attributes
-                :returns:   DB_driver on success, FALSE on failure
-		:rtype:	mixed
+		:param	string	$if_not_exists: Set to TRUE to add an 'IF NOT EXISTS' clause
+		:param	string	$attributes: An associative array of table attributes
+		:returns:  TRUE on success, FALSE on failure
+		:rtype:	bool
 
-                Create a new table. Usage:  See `Creating a table`_.
+		Creates a new table. Usage:  See `Creating a table`_.
 
-	.. method:: drop_column($table = '', $column_name = '')
+	.. method:: drop_column($table, $column_name)
 
 		:param	string	$table: Table name
-		:param	array	$column_name: Column to drop
-                :returns:   DB_driver on success, FALSE on failure
-		:rtype:	mixed
+		:param	array	$column_name: The column name to drop
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-                Drop a column from a table. Usage:  See `Dropping a Column From a Table`_.
+		Drops a column from a table. Usage:  See `Dropping a Column From a Table`_.
 
 	.. method:: drop_database($db_name)
 
 		:param	string	$db_name: Name of the database to drop
-                :returns:   TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-                Drop a database. Usage:  See `Creating and Dropping Databases`_.
+		Drops a database. Usage:  See `Creating and Dropping Databases`_.
 
-	.. method:: drop_table($table_name, $if_exists = FALSE)
+	.. method:: drop_table($table_name[, $if_exists = FALSE])
 
-		:param	string	$table: Name of the table to create
-		:param	string	$if_exists: TRUE to add an 'IF EXISTS' clause
-                :returns:   DB_driver on success, FALSE on failure
-		:rtype:	mixed
+		:param	string	$table: Name of the table to drop
+		:param	string	$if_exists: Set to TRUE to add an 'IF EXISTS' clause
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-                Drop a table. Usage:  See `Dropping a table`_.
+		Drops a table. Usage:  See `Dropping a table`_.
 
-	.. method:: modify_column($table = '', $field = array())
+	.. method:: modify_column($table, $field)
 
 		:param	string	$table: Table name
-		:param	array	$field: Column definitions
-		:returns:   TRUE on success, FALSE on failure
-		:rtype:	boolean
+		:param	array	$field: Column definition(s)
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-                Modify a column in a table. Usage:  See `Modifying a Column in a Table`_.
+		Modifies a table column. Usage:  See `Modifying a Column in a Table`_.
 
 	.. method:: rename_table($table_name, $new_table_name)
 
-		:param	string	$table: Name of the table
+		:param	string	$table: Current of the table
 		:param	string	$new_table_name: New name of the table
-                :returns:   DB_driver on success, FALSE on failure
-		:rtype:	mixed
-
-                Rename a table. Usage:  See `Renaming a table`_.
-
-
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
+		Renames a table. Usage:  See `Renaming a table`_.
\ No newline at end of file
diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst
index d15cef06d..0d8137dd7 100644
--- a/user_guide_src/source/database/utilities.rst
+++ b/user_guide_src/source/database/utilities.rst
@@ -9,7 +9,6 @@ database.
     :local:
     :depth: 2
 
-
 ******************************
 Initializing the Utility Class
 ******************************
@@ -248,66 +247,70 @@ Preference              Default Value           Options                 Descript
 Class Reference
 ***************
 
-.. class:: DB_utility
+.. class:: CI_DB_utility
 
-	.. method:: backup($params)
+	.. method:: backup([$params = array()])
 
-		:param	array	$params: associative array of backup preferences
+		:param	array	$params: An associative array of options
 		:returns:	void
-                :rtype:         void
-
-		Perform a database backup, per user preferences
+		:rtype:	void
 
-        .. method:: csv_from_results($query, $delim = ',', $newline = "\n", $enclosure = '"')
-
-                :param  object  $query:   DB_result with data to backup
-                :param  string  $delim:  Delimniter character for the CSV file, default is ','
-                :param  string  $newline:    Character to use for newlines, default is "\n"
-                :param  string  $enclosure:  Delimiter used for enclosure, default is '"'
-                :returns:   The generated CSV file as a string
-                :rtype:     string
+		Perform a database backup, per user preferences.
 
 	.. method:: database_exists($database_name)
 
-		:param	string	$database_name: name of the database to check for
+		:param	string	$database_name: Database name
 		:returns:	TRUE if the database exists, FALSE otherwise
-                :rtype:         boolean
+		:rtype:	bool
 
-		Check for the existence of a database
+		Check for the existence of a database.
 
 	.. method:: list_databases()
 
 		:returns:	Array of database names found
-                :rtype:         array
+		:rtype:	array
 
-		Retrieve all the database names
+		Retrieve a list of all the database names.
 
 	.. method:: optimize_database()
 
-		:returns:	Array of optimization messages, FALSE on failure
-                :rtype:         array
+		:returns:	Array of optimization messages or FALSE on failure
+		:rtype:	array
 
-		Optimizes a database
+		Optimizes the database.
 
 	.. method:: optimize_table($table_name)
 
-                :param  string  $table_name:    Name of the table to optimize
-		:returns:	Array of optimization messages, FALSE on failure
-                :rtype:         array
+		:param	string	$table_name:	Name of the table to optimize
+		:returns:	Array of optimization messages or FALSE on failure
+		:rtype:	array
 
-		Optimizes a database table
+		Optimizes a database table.
 
 	.. method:: repair_table($table_name)
 
-                :param  string  $table_name:    Name of the table to repair
-		:returns:	Array of repair messages, FALSE on failure
-                :rtype:         array
+		:param	string	$table_name:	Name of the table to repair
+		:returns:	Array of repair messages or FALSE on failure
+		:rtype:	array
+
+		Repairs a database table.
+
+	.. method:: csv_from_results($query[, $delim = ','[, $newline = "\n"[, $enclosure = '"']]])
+
+		:param	object	$query:	A database result object
+		:param	string	$delim: The CSV field delimiter to use
+		:param	string	$newline: The newline character to use
+		:param	string	$enclosure: The enclosure delimiter to use
+		:returns:	The generated CSV file as a string
+		:rtype:	string
+
+		Translates a database result object into a CSV document.
 
-		Repairs a database table
+	.. method:: xml_from_results($query[, $params = array()])
 
-        .. method:: xml_from_results($query, $params)
+		:param	object	$query: A database result object
+		:param	array	$params: An associative array of preferences
+		:returns:	The generated XML document as a string
+		:rtype:	string
 
-                :param  object  $query:   DB_result with data to backup
-                :param  array  $params:  Associative array of preferences
-                :returns:   The generated XML document as a string
-                :rtype:         string
+		Translates a database result object into an XML document.
\ No newline at end of file
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst
index f29ebf4ed..2d0ee23a3 100644
--- a/user_guide_src/source/libraries/encryption.rst
+++ b/user_guide_src/source/libraries/encryption.rst
@@ -533,6 +533,7 @@ Class Reference
 		:param	int	$length: Optional output length
 		:param	string	$info: Optional context/application-specific info
 		:returns:	A pseudo-random key or FALSE on failure
+		:rtype:	string
 
 		Derives a key from another, presumably weaker key.