Merge pull request #5505 from kenjis/fix-docs-dbmgmt/forge.rst

docs: improve dbmgmt/forge.rst

Author: kenjis

user_guide_src/source/dbmgmt/forge.rst

@@ -13,7 +13,7 @@ Initializing the Forge Class
 ****************************
 
 .. important:: In order to initialize the Forge class, your database
-    driver must already be running, since the forge class relies on it.
+    driver must already be running, since the Forge class relies on it.
 
 Load the Forge Class as follows::
 
@@ -40,7 +40,7 @@ Returns true/false based on success or failure::
         echo 'Database created!';
     }
 
-An optional second parameter set to true will add IF EXISTS statement
+An optional second parameter set to true will add ``IF EXISTS`` statement
 or will check if a database exists before create it (depending on DBMS).
 
 ::
@@ -91,13 +91,13 @@ There are several things you may wish to do when creating tables. Add
 fields, add keys to the table, alter columns. CodeIgniter provides a
 mechanism for this.
 
-Adding fields
+Adding Fields
 =============
 
 Fields are normally created via an associative array. Within the array, you must
-include a 'type' key that relates to the datatype of the field. For
+include a ``type`` key that relates to the datatype of the field. For
 example, INT, VARCHAR, TEXT, etc. Many datatypes (for example VARCHAR)
-also require a 'constraint' key.
+also require a ``constraint`` key.
 
 ::
 
@@ -111,14 +111,14 @@ also require a 'constraint' key.
 
 Additionally, the following key/values can be used:
 
--  unsigned/true : to generate "UNSIGNED" in the field definition.
--  default/value : to generate a default value in the field definition.
--  null/true : to generate "null" in the field definition. Without this,
+-  ``unsigned``/true : to generate "UNSIGNED" in the field definition.
+-  ``default``/value : to generate a default value in the field definition.
+-  ``null``/true : to generate "null" in the field definition. Without this,
    the field will default to "NOT null".
--  auto_increment/true : generates an auto_increment flag on the
+-  ``auto_increment``/true : generates an auto_increment flag on the
    field. Note that the field type must be a type that supports this,
    such as integer.
--  unique/true : to generate a unique key for the field definition.
+-  ``unique``/true : to generate a unique key for the field definition.
 
 ::
 
@@ -151,7 +151,7 @@ Additionally, the following key/values can be used:
     ];
 
 After the fields have been defined, they can be added using
-``$forge->addField($fields);`` followed by a call to the
+``$forge->addField($fields)`` followed by a call to the
 ``createTable()`` method.
 
 **$forge->addField()**
@@ -162,15 +162,13 @@ Passing strings as fields
 -------------------------
 
 If you know exactly how you want a field to be created, you can pass the
-string into the field definitions with addField()
-
-::
+string into the field definitions with ``addField()``::
 
     $forge->addField("label varchar(100) NOT NULL DEFAULT 'default label'");
 
 .. note:: Passing raw strings as fields cannot be followed by ``addKey()`` calls on those fields.
 
-.. note:: Multiple calls to addField() are cumulative.
+.. note:: Multiple calls to ``addField()`` are cumulative.
 
 Creating an id field
 --------------------
@@ -188,10 +186,10 @@ Adding Keys
 ===========
 
 Generally speaking, you'll want your table to have Keys. This is
-accomplished with $forge->addKey('field'). The optional second
+accomplished with ``$forge->addKey('field')``. The optional second
 parameter set to true will make it a primary key and the third
-parameter set to true will make it a unique key. Note that addKey()
-must be followed by a call to createTable().
+parameter set to true will make it a unique key. Note that ``addKey()``
+must be followed by a call to ``createTable()``.
 
 Multiple column non-primary keys must be sent as an array. Sample output
 below is for MySQL.
@@ -245,7 +243,7 @@ You can specify the desired action for the "on delete" and "on update" propertie
     $forge->addForeignKey(['users_id', 'users_name'], 'users', ['id', 'name'], 'CASCADE', 'CASCADE');
     // gives CONSTRAINT `TABLENAME_users_foreign` FOREIGN KEY(`users_id`, `users_name`) REFERENCES `users`(`id`, `name`) ON DELETE CASCADE ON UPDATE CASCADE
 
-Creating a table
+Creating a Table
 ================
 
 After fields and keys have been declared, you can create a new table
@@ -256,7 +254,7 @@ with
     $forge->createTable('table_name');
     // gives CREATE TABLE table_name
 
-An optional second parameter set to true adds an "IF NOT EXISTS" clause
+An optional second parameter set to true adds an ``IF NOT EXISTS`` clause
 into the definition
 
 ::
@@ -274,10 +272,10 @@ You could also pass optional table attributes, such as MySQL's ``ENGINE``::
     ``createTable()`` will always add them with your configured *charset*
     and *DBCollat* values, as long as they are not empty (MySQL only).
 
-Dropping a table
+Dropping a Table
 ================
 
-Execute a DROP TABLE statement and optionally add an IF EXISTS clause.
+Execute a ``DROP TABLE`` statement and optionally add an ``IF EXISTS`` clause.
 
 ::
 
@@ -287,7 +285,7 @@ Execute a DROP TABLE statement and optionally add an IF EXISTS clause.
     // Produces: DROP TABLE IF EXISTS `table_name`
     $forge->dropTable('table_name', true);
 
-A third parameter can be passed to add a "CASCADE" option, which might be required for some
+A third parameter can be passed to add a ``CASCADE`` option, which might be required for some
 drivers to handle removal of tables with foreign keys.
 
 ::
@@ -316,7 +314,7 @@ Execute a DROP KEY.
     // Produces: DROP INDEX `users_index` ON `tablename`
     $forge->dropKey('tablename', 'users_index');
 
-Renaming a table
+Renaming a Table
 ================
 
 Executes a TABLE rename
@@ -348,7 +346,7 @@ number of additional fields.
     // Executes: ALTER TABLE `table_name` ADD `preferences` TEXT
 
 If you are using MySQL or CUBIRD, then you can take advantage of their
-AFTER and FIRST clauses to position the new column.
+``AFTER`` and ``FIRST`` clauses to position the new column.
 
 Examples::
 
@@ -421,7 +419,7 @@ Class Reference
         :returns:    \CodeIgniter\Database\Forge instance (method chaining)
         :rtype:    \CodeIgniter\Database\Forge
 
-                Adds 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`_.
 
     .. php:method:: addForeignKey($fieldName, $tableName, $tableField[, $onUpdate = '', $onDelete = ''])
 
@@ -464,7 +462,7 @@ Class Reference
     .. php:method:: createDatabase($dbName[, $ifNotExists = false])
 
         :param    string    $db_name: Name of the database to create
-        :param    string    $ifNotExists: Set to true to add an 'IF NOT EXISTS' clause or check if database exists
+        :param    string    $ifNotExists: Set to true to add an ``IF NOT EXISTS`` clause or check if database exists
         :returns:    true on success, false on failure
         :rtype:    bool
 
@@ -473,12 +471,12 @@ Class Reference
     .. php:method:: createTable($table[, $if_not_exists = false[, array $attributes = []]])
 
         :param    string    $table: Name of the table to create
-        :param    string    $if_not_exists: Set to true to add an 'IF NOT EXISTS' clause
+        :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:  Query object on success, false on failure
         :rtype:    mixed
 
-        Creates a new table. Usage:  See `Creating a table`_.
+        Creates a new table. Usage:  See `Creating a Table`_.
 
     .. php:method:: dropColumn($table, $column_name)
 
@@ -500,11 +498,11 @@ Class Reference
     .. php:method:: dropTable($table_name[, $if_exists = false])
 
         :param    string    $table: Name of the table to drop
-        :param    string    $if_exists: Set to true to add an 'IF EXISTS' clause
+        :param    string    $if_exists: Set to true to add an ``IF EXISTS`` clause
         :returns:    true on success, false on failure
         :rtype:    bool
 
-        Drops a table. Usage:  See `Dropping a table`_.
+        Drops a table. Usage:  See `Dropping a Table`_.
 
     .. php:method:: modifyColumn($table, $field)
 
@@ -522,4 +520,4 @@ Class Reference
         :returns:  Query object on success, false on failure
         :rtype:    mixed
 
-        Renames a table. Usage:  See `Renaming a table`_.
+        Renames a table. Usage:  See `Renaming a Table`_.