From 83a4ee1ea031fc4953bf63c0cba4fb9b75586795 Mon Sep 17 00:00:00 2001
From: Aparup Banerjee <aparup@moodle.com>
Date: Fri, 27 Jan 2012 00:10:45 +0800
Subject: [PATCH] MDL-31251 documentation : improved core ddl API phpdocs.
 (used moodlecheck plugin)

---
 lib/ddl/database_manager.php       | 191 ++++++-----
 lib/ddl/mssql_sql_generator.php    |   2 +-
 lib/ddl/mysql_sql_generator.php    |   2 +-
 lib/ddl/oracle_sql_generator.php   |   2 +-
 lib/ddl/postgres_sql_generator.php |   2 +-
 lib/ddl/sql_generator.php          | 501 +++++++++++++++++++++--------
 lib/ddl/sqlite_sql_generator.php   |   2 +-
 7 files changed, 475 insertions(+), 227 deletions(-)

diff --git a/lib/ddl/database_manager.php b/lib/ddl/database_manager.php
index 13036c91a2c..79afe2b965f 100644
--- a/lib/ddl/database_manager.php
+++ b/lib/ddl/database_manager.php
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -17,10 +16,10 @@
 
 
 /**
- * Database manager instance is responsible for all database structure
- * modifications.
+ * Database manager instance is responsible for all database structure modifications.
  *
  * @package    core
+ * @category   ddl
  * @subpackage ddl
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
@@ -31,18 +30,29 @@
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * Database manager instance is responsible for all database structure
- * modifications. It is using db specific generators to find out
- * the correct SQL syntax to do that.
+ * Database manager instance is responsible for all database structure modifications.
+ *
+ * It is using db specific generators to find out the correct SQL syntax to do that.
+ *
+ * @package    core
+ * @category   ddl
+ * @subpackage ddl
+ * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
+ *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
+ *             2008 Petr Skoda                   http://skodak.org
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class database_manager {
 
+    /** @var moodle_database A moodle_database driver speific instance.*/
     protected $mdb;
-    public $generator; // public because XMLDB editor needs to access it
+    /** @var sql_generator A driver specific SQL generator instance. Public because XMLDB editor needs to access it.*/
+    public $generator;
 
     /**
-     * Creates new database manager
-     * @param object moodle_database instance
+     * Creates a new database manager instance.
+     * @param moodle_database $mdb A moodle_database driver specific instance.
+     * @param sql_generator $generator A driver specific SQL generator instance.
      */
     public function __construct($mdb, $generator) {
         global $CFG;
@@ -52,7 +62,7 @@ class database_manager {
     }
 
     /**
-     * Release all resources
+     * Releases all resources
      */
     public function dispose() {
         if ($this->generator) {
@@ -65,10 +75,8 @@ class database_manager {
     /**
      * This function will execute an array of SQL commands.
      *
-     * @exception ddl_exception if error found
-     *
-     * @param array $sqlarr array of sql statements to execute
-     * @return void
+     * @param array $sqlarr Array of sql statements to execute.
+     * @throws ddl_exception This exception is thrown if any error is found.
      */
     protected function execute_sql_arr(array $sqlarr) {
         foreach ($sqlarr as $sql) {
@@ -77,12 +85,10 @@ class database_manager {
     }
 
     /**
-     * Execute a given sql command string
+     * Execute a given sql command string.
      *
-     * @exception ddl_exception if error found
-     *
-     * @param string $command The sql string you wish to be executed.
-     * @return void
+     * @param string $sql The sql string you wish to be executed.
+     * @throws ddl_exception This exception is thrown if any error is found.
      */
     protected function execute_sql($sql) {
         if (!$this->mdb->change_database_structure($sql)) {
@@ -92,10 +98,10 @@ class database_manager {
     }
 
     /**
-     * Given one xmldb_table, check if it exists in DB (true/false)
+     * Given one xmldb_table, check if it exists in DB (true/false).
      *
-     * @param mixed the table to be searched (string name or xmldb_table instance)
-     * @return boolean true/false
+     * @param mixed $table The table to be searched (string name or xmldb_table instance).
+     * @return bool true/false True is a table exists, false otherwise.
      */
     public function table_exists($table) {
         if (!is_string($table) and !($table instanceof xmldb_table)) {
@@ -106,8 +112,8 @@ class database_manager {
 
     /**
      * Reset a sequence to the id field of a table.
-     * @param string $table name of table
-     * @return success
+     * @param string $table Name of table.
+     * @throws ddl_exception|ddl_table_missing_exception Exception thrown upon reset errors.
      */
     public function reset_sequence($table) {
         if (!is_string($table) and !($table instanceof xmldb_table)) {
@@ -127,11 +133,12 @@ class database_manager {
     }
 
     /**
-     * Given one xmldb_field, check if it exists in DB (true/false)
+     * Given one xmldb_field, check if it exists in DB (true/false).
      *
-     * @param mixed the table to be searched (string name or xmldb_table instance)
-     * @param mixed the field to be searched for (string name or xmldb_field instance)
-     * @return boolean true/false
+     * @param mixed $table The table to be searched (string name or xmldb_table instance).
+     * @param mixed $field The field to be searched for (string name or xmldb_field instance).
+     * @return boolean true is exists false otherwise.
+     * @throws ddl_table_missing_exception
      */
     public function field_exists($table, $field) {
     /// Calculate the name of the table
@@ -165,9 +172,10 @@ class database_manager {
      * Given one xmldb_index, the function returns the name of the index in DB
      * of false if it doesn't exist
      *
-     * @param object $xmldb_table table to be searched
-     * @param object $xmldb_index the index to be searched
-     * @return string index name of false
+     * @param xmldb_table $xmldb_table table to be searched
+     * @param xmldb_index $xmldb_index the index to be searched
+     * @return string|bool Index name or false if no indexes are found.
+     * @throws ddl_table_missing_exception Thrown when table is not found.
      */
     public function find_index_name(xmldb_table $xmldb_table, xmldb_index $xmldb_index) {
     /// Calculate the name of the table
@@ -200,11 +208,11 @@ class database_manager {
     }
 
     /**
-     * Given one xmldb_index, check if it exists in DB (true/false)
+     * Given one xmldb_index, check if it exists in DB (true/false).
      *
-     * @param object $xmldb_table the table to be searched
-     * @param object $xmldb_index the index to be searched for
-     * @return boolean true/false
+     * @param xmldb_table $xmldb_table The table to be searched.
+     * @param xmldb_index $xmldb_index The index to be searched for.
+     * @return boolean true id index exists, false otherwise.
      */
     public function index_exists(xmldb_table $xmldb_table, xmldb_index $xmldb_index) {
         if (!$this->table_exists($xmldb_table)) {
@@ -219,11 +227,11 @@ class database_manager {
      * to 1 "enum-like" constraint. So, if more than one is returned, only the first one will be
      * retrieved by this function.
      *
-     * TODO: Moodle 2.1 - Drop find_check_constraint_name()
+     * @todo MDL-31147 Moodle 2.1 - Drop find_check_constraint_name()
      *
-     * @param xmldb_table the table to be searched
-     * @param xmldb_field the field to be searched
-     * @return string check constraint name or false
+     * @param xmldb_table $xmldb_table The table to be searched.
+     * @param xmldb_field $xmldb_field The field to be searched.
+     * @return string|bool check constraint name or false
      */
     public function find_check_constraint_name(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
 
@@ -256,8 +264,8 @@ class database_manager {
      *
      * TODO: Moodle 2.1 - Drop check_constraint_exists()
      *
-     * @param xmldb_table the table
-     * @param xmldb_field the field to be searched for any existing constraint
+     * @param xmldb_table $xmldb_table The table.
+     * @param xmldb_field $xmldb_field The field to be searched for any existing constraint.
      * @return boolean true/false
      */
     public function check_constraint_exists(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -271,9 +279,9 @@ class database_manager {
      * Given one xmldb_key, the function returns the name of the key in DB (if exists)
      * of false if it doesn't exist
      *
-     * @param xmldb_table the table to be searched
-     * @param xmldb_key the key to be searched
-     * @return string key name of false
+     * @param xmldb_table $xmldb_table The table to be searched.
+     * @param xmldb_key $xmldb_key The key to be searched.
+     * @return string key name if found
      */
     public function find_key_name(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
 
@@ -316,7 +324,7 @@ class database_manager {
     /**
      * This function will delete all tables found in XMLDB file from db
      *
-     * @param $file full path to the XML file to be used
+     * @param string $file Full path to the XML file to be used.
      * @return void
      */
     public function delete_tables_from_xmldb_file($file) {
@@ -354,7 +362,7 @@ class database_manager {
      * and all the associated objects (keys, indexes, constraints, sequences, triggers)
      * will be dropped too.
      *
-     * @param xmldb_table table object (just the name is mandatory)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
      * @return void
      */
     public function drop_table(xmldb_table $xmldb_table) {
@@ -399,7 +407,7 @@ class database_manager {
     /**
      * This function will load one entire XMLDB file and call install_from_xmldb_structure.
      *
-     * @param $file full path to the XML file to be used
+     * @param string $file full path to the XML file to be used
      * @return void
      */
     public function install_from_xmldb_file($file) {
@@ -411,8 +419,8 @@ class database_manager {
     /**
      * This function will load one entire XMLDB file and call install_from_xmldb_structure.
      *
-     * @param $file full path to the XML file to be used
-     * @param $tablename the name of the table.
+     * @param string $file full path to the XML file to be used
+     * @param string $tablename the name of the table.
      * @param bool $cachestructures boolean to decide if loaded xmldb structures can be safely cached
      *             useful for testunits loading the enormous main xml file hundred of times (100x)
      */
@@ -445,7 +453,7 @@ class database_manager {
      * This function will generate all the needed SQL statements, specific for each
      * RDBMS type and, finally, it will execute all those statements against the DB.
      *
-     * @param object $structure xmldb_structure object
+     * @param stdClass $xmldb_structure xmldb_structure object.
      * @return void
      */
     public function install_from_xmldb_structure($xmldb_structure) {
@@ -460,7 +468,7 @@ class database_manager {
      * This function will create the table passed as argument with all its
      * fields/keys/indexes/sequences, everything based in the XMLDB object
      *
-     * @param xmldb_table table object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (full specs are required).
      * @return void
      */
     public function create_table(xmldb_table $xmldb_table) {
@@ -482,7 +490,7 @@ class database_manager {
      * If table already exists ddl_exception will be thrown, please make sure
      * the table name does not collide with existing normal table!
      *
-     * @param xmldb_table table object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (full specs are required).
      * @return void
      */
     public function create_temp_table(xmldb_table $xmldb_table) {
@@ -505,7 +513,7 @@ class database_manager {
      *
      * It is recommended to drop temp table when not used anymore.
      *
-     * @param xmldb_table table object
+     * @param xmldb_table $xmldb_table Table object.
      * @return void
      */
     public function drop_temp_table(xmldb_table $xmldb_table) {
@@ -526,8 +534,8 @@ class database_manager {
      * This function will rename the table passed as argument
      * Before renaming the index, the function will check it exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param string new name of the index
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param string $newname New name of the index.
      * @return void
      */
     public function rename_table(xmldb_table $xmldb_table, $newname) {
@@ -563,8 +571,8 @@ class database_manager {
     /**
      * This function will add the field to the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function add_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -589,8 +597,8 @@ class database_manager {
     /**
      * This function will drop the field from the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (just the name is mandatory)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function drop_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -614,8 +622,8 @@ class database_manager {
     /**
      * This function will change the type of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_type(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -639,8 +647,8 @@ class database_manager {
     /**
      * This function will change the precision of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_precision(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -651,8 +659,8 @@ class database_manager {
     /**
      * This function will change the unsigned/signed of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_unsigned(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -663,8 +671,8 @@ class database_manager {
     /**
      * This function will change the nullability of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_notnull(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -676,8 +684,8 @@ class database_manager {
      * This function will change the default of the field in the table passed as arguments
      * One null value in the default field means delete the default
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_default(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -703,8 +711,8 @@ class database_manager {
      *
      * TODO: Moodle 2.1 - Drop drop_enum_from_field()
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function drop_enum_from_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -733,9 +741,9 @@ class database_manager {
      * This function will rename the field in the table passed as arguments
      * Before renaming the field, the function will check it exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field index object (full specs are required)
-     * @param string new name of the field
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
+     * @param string $newname New name of the field.
      * @return void
      */
     public function rename_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field, $newname) {
@@ -776,7 +784,12 @@ class database_manager {
     /**
      * This function will check, for the given table and field, if there there is any dependency
      * preventing the field to be modified. It's used by all the public methods that perform any
-     * DDL change on fields, throwing one ddl_dependency_exception if dependencies are found
+     * DDL change on fields, throwing one ddl_dependency_exception if dependencies are found.
+     *
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
+     * @return void
+     * @throws ddl_dependency_exception|ddl_field_missing_exception|ddl_table_missing_exception if dependency not met.
      */
     private function check_field_dependencies(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
 
@@ -805,8 +818,8 @@ class database_manager {
     /**
      * This function will create the key in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_key index object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_key $xmldb_key Index object (full specs are required).
      * @return void
      */
     public function add_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
@@ -825,8 +838,8 @@ class database_manager {
     /**
      * This function will drop the key in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_key key object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_key $xmldb_key Key object (full specs are required).
      * @return void
      */
     public function drop_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
@@ -845,9 +858,9 @@ class database_manager {
      * This function will rename the key in the table passed as arguments
      * Experimental. Shouldn't be used at all in normal installation/upgrade!
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_key key object (full specs are required)
-     * @param string new name of the key
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_key $xmldb_key key object (full specs are required).
+     * @param string $newname New name of the key.
      * @return void
      */
     public function rename_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key, $newname) {
@@ -869,8 +882,8 @@ class database_manager {
      * This function will create the index in the table passed as arguments
      * Before creating the index, the function will check it doesn't exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_index index object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_index $xmldb_intex Index object (full specs are required).
      * @return void
      */
     public function add_index($xmldb_table, $xmldb_intex) {
@@ -896,8 +909,8 @@ class database_manager {
      * This function will drop the index in the table passed as arguments
      * Before dropping the index, the function will check it exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_index index object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_index $xmldb_intex Index object (full specs are required).
      * @return void
      */
     public function drop_index($xmldb_table, $xmldb_intex) {
@@ -924,9 +937,9 @@ class database_manager {
      * Before renaming the index, the function will check it exists
      * Experimental. Shouldn't be used at all!
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_index index object (full specs are required)
-     * @param string new name of the index
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_index $xmldb_intex Index object (full specs are required).
+     * @param string $newname New name of the index.
      * @return void
      */
     public function rename_index($xmldb_table, $xmldb_intex, $newname) {
diff --git a/lib/ddl/mssql_sql_generator.php b/lib/ddl/mssql_sql_generator.php
index 3c9b41de283..fa7cbadabc4 100644
--- a/lib/ddl/mssql_sql_generator.php
+++ b/lib/ddl/mssql_sql_generator.php
@@ -20,7 +20,7 @@
  * MSSQL specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
diff --git a/lib/ddl/mysql_sql_generator.php b/lib/ddl/mysql_sql_generator.php
index 3004c7680c8..5f893633c3e 100644
--- a/lib/ddl/mysql_sql_generator.php
+++ b/lib/ddl/mysql_sql_generator.php
@@ -20,7 +20,7 @@
  * Mysql specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
diff --git a/lib/ddl/oracle_sql_generator.php b/lib/ddl/oracle_sql_generator.php
index 9450388dcc2..80039a5df7e 100644
--- a/lib/ddl/oracle_sql_generator.php
+++ b/lib/ddl/oracle_sql_generator.php
@@ -20,7 +20,7 @@
  * Oracle specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
diff --git a/lib/ddl/postgres_sql_generator.php b/lib/ddl/postgres_sql_generator.php
index 5e2a3c8ee48..acde9d2d4a1 100644
--- a/lib/ddl/postgres_sql_generator.php
+++ b/lib/ddl/postgres_sql_generator.php
@@ -20,7 +20,7 @@
  * PostgreSQL specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
diff --git a/lib/ddl/sql_generator.php b/lib/ddl/sql_generator.php
index 203ccf3686f..751715cea8a 100644
--- a/lib/ddl/sql_generator.php
+++ b/lib/ddl/sql_generator.php
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -17,13 +16,13 @@
 
 
 /**
- * This class represent the base generator class where all the
- * needed functions to generate proper SQL are defined.
+ * This class represent the base generator class where all the needed functions to generate proper SQL are defined.
  *
  * The rest of classes will inherit, by default, the same logic.
  * Functions will be overridden as needed to generate correct SQL.
  *
  * @package    core
+ * @category   ddl
  * @subpackage ddl
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
@@ -34,6 +33,13 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * Abstract sql generator class, base for all db specific implementations.
+ *
+ * @package    core
+ * @category   ddl
+ * @subpackage ddl
+ * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
+ *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class sql_generator {
 
@@ -42,96 +48,146 @@ abstract class sql_generator {
 /// that, by default, inherit this configuration.
 /// To change any of them, do it in extended classes instead.
 
-    public $quote_string = '"';   // String used to quote names
+    /** @var string Used to quote names. */
+    public $quote_string = '"';
 
-    public $statement_end = ';'; // String to be automatically added at the end of each statement
+    /** @var string To be automatically added at the end of each statement. */
+    public $statement_end = ';';
 
-    public $quote_all    = false; // To decide if we want to quote all the names or only the reserved ones
+    /** @var bool To decide if we want to quote all the names or only the reserved ones. */
+    public $quote_all    = false;
 
-    public $integer_to_number = false;  // To create all the integers as NUMBER(x) (also called DECIMAL, NUMERIC...)
-    public $float_to_number   = false;  // To create all the floats as NUMBER(x) (also called DECIMAL, NUMERIC...)
+    /** @var bool To create all the integers as NUMBER(x) (also called DECIMAL, NUMERIC...). */
+    public $integer_to_number = false;
+    /** @var bool To create all the floats as NUMBER(x) (also called DECIMAL, NUMERIC...). */
+    public $float_to_number   = false;
 
-    public $number_type = 'NUMERIC';    // Proper type for NUMBER(x) in this DB
+    /** @var string Proper type for NUMBER(x) in this DB. */
+    public $number_type = 'NUMERIC';
 
-    public $unsigned_allowed = true;    // To define in the generator must handle unsigned information
-    public $default_for_char = null;      // To define the default to set for NOT NULLs CHARs without default (null=do nothing)
+    /** @var bool To define in the generator must handle unsigned information.*/
+    public $unsigned_allowed = true;
+    /** @var string To define the default to set for NOT NULLs CHARs without default (null=do nothing).*/
+    public $default_for_char = null;
 
-    public $drop_default_value_required = false; //To specify if the generator must use some DEFAULT clause to drop defaults
-    public $drop_default_value = ''; //The DEFAULT clause required to drop defaults
+    /** @var bool To specify if the generator must use some DEFAULT clause to drop defaults.*/
+    public $drop_default_value_required = false;
+    /** @var string The DEFAULT clause required to drop defaults.*/
+    public $drop_default_value = '';
 
-    public $default_after_null = true;  //To decide if the default clause of each field must go after the null clause
-
-    public $specify_nulls = false;  //To force the generator if NULL clauses must be specified. It shouldn't be necessary
-                                 //but some mssql drivers require them or everything is created as NOT NULL :-(
-
-    public $primary_key_name = null; //To force primary key names to one string (null=no force)
-
-    public $primary_keys = true;  // Does the generator build primary keys
-    public $unique_keys = false;  // Does the generator build unique keys
-    public $foreign_keys = false; // Does the generator build foreign keys
-
-    public $drop_primary_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop PKs
-                               // with automatic replace for TABLENAME and KEYNAME
-
-    public $drop_unique_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop UKs
-                               // with automatic replace for TABLENAME and KEYNAME
-
-    public $drop_foreign_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop FKs
-                               // with automatic replace for TABLENAME and KEYNAME
-
-    public $sequence_extra_code = true; //Does the generator need to add extra code to generate the sequence fields
-    public $sequence_name = 'auto_increment'; //Particular name for inline sequences in this generator
-    public $sequence_name_small = false; //Different name for small (4byte) sequences or false if same
-    public $sequence_only = false; //To avoid to output the rest of the field specs, leaving only the name and the sequence_name publiciable
-
-    public $add_table_comments  = true;  // Does the generator need to add code for table comments
-
-    public $add_after_clause = false; // Does the generator need to add the after clause for fields
-
-    public $prefix_on_names = true; //Does the generator need to prepend the prefix to all the key/index/sequence/trigger/check names
-
-    public $names_max_length = 30; //Max length for key/index/sequence/trigger/check names (keep 30 for all!)
-
-    public $concat_character = '||'; //Characters to be used as concatenation operator. If not defined
-                                  //MySQL CONCAT function will be used
-
-    public $rename_table_sql = 'ALTER TABLE OLDNAME RENAME TO NEWNAME'; //SQL sentence to rename one table, both
-                                  //OLDNAME and NEWNAME are dynamically replaced
-
-    public $drop_table_sql = 'DROP TABLE TABLENAME'; //SQL sentence to drop one table
-                                  //TABLENAME is dynamically replaced
-
-    public $alter_column_sql = 'ALTER TABLE TABLENAME ALTER COLUMN COLUMNSPECS'; //The SQL template to alter columns
-
-    public $alter_column_skip_default = false; //The generator will skip the default clause on alter columns
-
-    public $alter_column_skip_type = false; //The generator will skip the type clause on alter columns
-
-    public $alter_column_skip_notnull = false; //The generator will skip the null/notnull clause on alter columns
-
-    public $rename_column_sql = 'ALTER TABLE TABLENAME RENAME COLUMN OLDFIELDNAME TO NEWFIELDNAME';
-                                  ///TABLENAME, OLDFIELDNAME and NEWFIELDNAME are dyanmically replaced
-
-    public $drop_index_sql = 'DROP INDEX INDEXNAME'; //SQL sentence to drop one index
-                                  //TABLENAME, INDEXNAME are dynamically replaced
-
-    public $rename_index_sql = 'ALTER INDEX OLDINDEXNAME RENAME TO NEWINDEXNAME'; //SQL sentence to rename one index
-                                  //TABLENAME, OLDINDEXNAME, NEWINDEXNAME are dynamically replaced
-
-    public $rename_key_sql = 'ALTER TABLE TABLENAME CONSTRAINT OLDKEYNAME RENAME TO NEWKEYNAME'; //SQL sentence to rename one key
-                                  //TABLENAME, OLDKEYNAME, NEWKEYNAME are dynamically replaced
-
-    public $prefix;         // Prefix to be used for all the DB objects
-
-    public $reserved_words; // List of reserved words (in order to quote them properly)
-
-    public $mdb;
-
-    protected $temptables; // Control existing temptables
+    /** @var bool To decide if the default clause of each field must go after the null clause.*/
+    public $default_after_null = true;
 
     /**
-     * Creates new sql_generator
-     * @param object moodle_database instance
+     * @var bool To force the generator if NULL clauses must be specified. It shouldn't be necessary.
+     * note: some mssql drivers require them or everything is created as NOT NULL :-(
+     */
+    public $specify_nulls = false;
+
+    /** @var string To force primary key names to one string (null=no force).*/
+    public $primary_key_name = null;
+
+    /** @var bool True if the generator builds primary keys.*/
+    public $primary_keys = true;
+    /** @var bool True if the generator builds unique keys.*/
+    public $unique_keys = false;
+    /** @var bool True if the generator builds foreign keys.*/
+    public $foreign_keys = false;
+
+    /**
+     * @var string Template to drop PKs.
+     * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+     */
+    public $drop_primary_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
+
+    /**
+     * @var string Template to drop UKs.
+     * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+     */
+    public $drop_unique_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
+
+    /** @var string Template to drop FKs.
+     * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+     */
+    public $drop_foreign_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
+
+    /** @var bool True if the generator needs to add extra code to generate the sequence fields.*/
+    public $sequence_extra_code = true;
+    /** @var string The particular name for inline sequences in this generator.*/
+    public $sequence_name = 'auto_increment';
+    /** @var string|bool Different name for small (4byte) sequences or false if same.*/
+    public $sequence_name_small = false;
+    /**
+     * @var bool To avoid outputting the rest of the field specs, leaving only the name and the sequence_name returned. 
+     * @see getFieldSQL()
+     */
+    public $sequence_only = false;
+
+    /** @var bool True if the generator needs to add code for table comments.*/
+    public $add_table_comments  = true;
+
+    /** @var bool True if the generator needs to add the after clause for fields.*/
+    public $add_after_clause = false;
+
+    /**
+     * @var bool True if the generator needs to prepend the prefix to all the key/index/sequence/trigger/check names.
+     * @see $prefix
+     */
+    public $prefix_on_names = true;
+
+    /** @var int Maximum length for key/index/sequence/trigger/check names (keep 30 for all!).*/
+    public $names_max_length = 30;
+
+    /** @var string Characters to be used as concatenation operator.
+     * If not defined, MySQL CONCAT function will be used.
+     */
+    public $concat_character = '||';
+
+    /** @var string SQL sentence to rename one table, both 'OLDNAME' and 'NEWNAME' keywords are dynamically replaced.*/
+    public $rename_table_sql = 'ALTER TABLE OLDNAME RENAME TO NEWNAME';
+
+    /** @var string SQL sentence to drop one table where the 'TABLENAME' keyword is dynamically replaced.*/
+    public $drop_table_sql = 'DROP TABLE TABLENAME';
+
+    /** @var string The SQL template to alter columns where the 'TABLENAME' and 'COLUMNSPECS' keywords are dynamically replaced.*/
+    public $alter_column_sql = 'ALTER TABLE TABLENAME ALTER COLUMN COLUMNSPECS';
+
+    /** @var bool The generator will skip the default clause on alter columns.*/
+    public $alter_column_skip_default = false;
+
+    /** @var bool The generator will skip the type clause on alter columns.*/
+    public $alter_column_skip_type = false;
+
+    /** @var bool The generator will skip the null/notnull clause on alter columns.*/
+    public $alter_column_skip_notnull = false;
+
+    /** @var string SQL sentence to rename one column where 'TABLENAME', 'OLDFIELDNAME' and 'NEWFIELDNAME' keywords are dynamically replaced.*/
+    public $rename_column_sql = 'ALTER TABLE TABLENAME RENAME COLUMN OLDFIELDNAME TO NEWFIELDNAME';
+
+    /** @var string SQL sentence to drop one index where 'TABLENAME', 'INDEXNAME' keywords are dynamically replaced.*/
+    public $drop_index_sql = 'DROP INDEX INDEXNAME';
+
+    /** @var string SQL sentence to rename one index where 'TABLENAME', 'OLDINDEXNAME' and 'NEWINDEXNAME' are dynamically replaced.*/
+    public $rename_index_sql = 'ALTER INDEX OLDINDEXNAME RENAME TO NEWINDEXNAME';
+
+    /** @var string SQL sentence to rename one key 'TABLENAME', 'OLDKEYNAME' and 'NEWKEYNAME' are dynamically replaced.*/
+    public $rename_key_sql = 'ALTER TABLE TABLENAME CONSTRAINT OLDKEYNAME RENAME TO NEWKEYNAME';
+
+    /** @var string The prefix to be used for all the DB objects.*/
+    public $prefix;
+
+    /** @var string List of reserved words (in order to quote them properly).*/
+    public $reserved_words;
+
+    /** @var moodle_database The moodle_database instance.*/
+    public $mdb;
+    /** @var Control existing temptables.*/
+    protected $temptables;
+
+    /**
+     * Creates a new sql_generator.
+     * @param moodle_database $mdb The moodle_database object instance.
+     * @param moodle_temptables $temptables The optional moodle_temptables instance, null by default.
      */
     public function __construct($mdb, $temptables = null) {
         $this->prefix         = $mdb->get_prefix();
@@ -141,14 +197,18 @@ abstract class sql_generator {
     }
 
     /**
-     * Release all resources
+     * Releases all resources.
      */
     public function dispose() {
         $this->mdb = null;
     }
 
     /**
-     * Given one string (or one array), ends it with statement_end
+     * Given one string (or one array), ends it with $statement_end .
+     * 
+     * @see $statement_end
+     *
+     * @param array|string $input SQL statement(s).
      */
     public function getEndedStatements($input) {
 
@@ -164,9 +224,9 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table, check if it exists in DB (true/false)
+     * Given one xmldb_table, checks if it exists in DB (true/false).
      *
-     * @param mixed the table to be searched (string name or xmldb_table instance)
+     * @param mixed $table The table to be searched (string name or xmldb_table instance).
      * @return boolean true/false
      */
     public function table_exists($table) {
@@ -185,7 +245,11 @@ abstract class sql_generator {
     }
 
     /**
-     * This function will return the SQL code needed to create db tables and statements
+     * This function will return the SQL code needed to create db tables and statements.
+     *
+     * @param xmldb_structure $xmldb_structure An xmldb_structure instance.
+     * 
+     * @see xmldb_structure
      */
     public function getCreateStructureSQL($xmldb_structure) {
         $results = array();
@@ -200,11 +264,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table, returns it's correct name, depending of all the parametrization
+     * Given one xmldb_table, this returns it's correct name, depending of all the parameterization.
+     * eg: This appends $prefix to the table name.
+     * 
+     * @see $prefix
      *
-     * @param xmldb_table table whose name we want
-     * @param boolean to specify if the name must be quoted (if reserved word, only!)
-     * @return string the correct name of the table
+     * @param xmldb_table $xmldb_table The table whose name we want.
+     * @param boolean $quoted To specify if the name must be quoted (if reserved word, only!).
+     * @return string The correct name of the table.
      */
     public function getTableName(xmldb_table $xmldb_table, $quoted=true) {
     /// Get the name
@@ -220,7 +287,11 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_table, returns the SQL statements
-     * to create it (inside one array)
+     * to create it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table An xmldb_table instance.
+     * @return array An array of SQL statements, starting with the table creation SQL followed
+     * by any of its comments, indexes and sequence creation SQL statements.
      */
     public function getCreateTableSQL($xmldb_table) {
 
@@ -345,7 +416,12 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_index, returns the SQL statements
-     * needed to create it (in array)
+     * needed to create it (in array).
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to create the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to create.
+     * @return array An array of SQL statements to create the index.
+     * @throws coding_exception Thrown if the xmldb_index does not validate with the xmldb_table.
      */
     public function getCreateIndexSQL($xmldb_table, $xmldb_index) {
         if ($error = $xmldb_index->validateDefinition($xmldb_table)) {
@@ -368,7 +444,17 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one correct xmldb_field, returns the complete SQL line to create it
+     * Given one correct xmldb_field, returns the complete SQL line to create it.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+     * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+     * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+     * @param string $specify_nulls_clause To force a specific null clause, NULL by default.
+     * @param bool $specify_field_name Flag to specify fieldname in return.
+     * @return string The field generating SQL statement.
+     * @throws coding_exception Thrown when xmldb_field doesn't validate with the xmldb_table.
      */
     public function getFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL, $specify_nulls_clause = NULL, $specify_field_name = true)  {
         if ($error = $xmldb_field->validateDefinition($xmldb_table)) {
@@ -453,7 +539,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one correct xmldb_key, returns its specs
+     * Given one correct xmldb_key, returns its specs.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key's specifications requested.
+     * @return string SQL statement about the xmldb_key.
      */
     public function getKeySQL($xmldb_table, $xmldb_key) {
 
@@ -492,6 +582,9 @@ abstract class sql_generator {
 
     /**
      * Give one xmldb_field, returns the correct "default value" for the current configuration
+     *
+     * @param xmldb_field $xmldb_field The field.
+     * @return The default value of the field.
      */
     public function getDefaultValue($xmldb_field) {
 
@@ -529,7 +622,10 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_field, returns the correct "default clause" for the current configuration
+     * Given one xmldb_field, returns the correct "default clause" for the current configuration.
+     *
+     * @param xmldb_field $xmldb_field The xmldb_field.
+     * @return The SQL clause for generating the default value as in $xmldb_field.
      */
     public function getDefaultClause($xmldb_field) {
 
@@ -544,7 +640,11 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_table and the new name, returns the SQL statements
-     * to rename it (inside one array)
+     * to rename it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The table to rename.
+     * @param string $newname The new name to rename the table to.
+     * @return array SQL statement(s) to rename the table.
      */
     public function getRenameTableSQL($xmldb_table, $newname) {
 
@@ -566,7 +666,10 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_table and the new name, returns the SQL statements
-     * to drop it (inside one array)
+     * to drop it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The table to drop.
+     * @return array SQL statement(s) for dropping the specified table.
      */
     public function getDropTableSQL($xmldb_table) {
 
@@ -584,7 +687,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add the field to the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add the field to the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+     * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+     * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+     * @return array The SQL statement for adding a field to the table.
      */
     public function getAddFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL) {
 
@@ -612,7 +722,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop the field from the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop the field from the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @return array The SQL statement for dropping a field from the table.
      */
     public function getDropFieldSQL($xmldb_table, $xmldb_field) {
 
@@ -629,7 +743,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to alter the field in the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to alter the field in the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+     * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+     * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+     * @return string The field altering SQL statement.
      */
     public function getAlterFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL) {
 
@@ -663,7 +784,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to modify the default of the field in the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to modify the default of the field in the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to get the modified default value from.
+     * @return array The SQL statement for modifying the default value.
      */
     public function getModifyDefaultSQL($xmldb_table, $xmldb_field) {
 
@@ -685,7 +810,12 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_field and the new name, returns the SQL statements
-     * to rename it (inside one array)
+     * to rename it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to get the renamed field from.
+     * @param string $newname The new name to rename the field to.
+     * @return array The SQL statements for renaming the field.
      */
     public function getRenameFieldSQL($xmldb_table, $xmldb_field, $newname) {
 
@@ -717,7 +847,11 @@ abstract class sql_generator {
 
     /**
      * Given one xmldb_table and one xmldb_key, return the SQL statements needed to add the key to the table
-     * note that undelying indexes will be added as parametrised by $xxxx_keys and $xxxx_index parameters
+     * note that undelying indexes will be added as parametrised by $xxxx_keys and $xxxx_index parameters.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key to add.
+     * @return array SQL statement to add the xmldb_key.
      */
     public function getAddKeySQL($xmldb_table, $xmldb_key) {
 
@@ -757,7 +891,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table
+     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key to drop.
+     * @return array SQL statement to drop the xmldb_key.
      */
     public function getDropKeySQL($xmldb_table, $xmldb_key) {
 
@@ -826,8 +964,12 @@ abstract class sql_generator {
     /**
      * Given one xmldb_table and one xmldb_key, return the SQL statements needed to rename the key in the table
      * Experimental! Shouldn't be used at all!
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key to rename.
+     * @param string $newname The xmldb_key's new name.
+     * @return array SQL statement to rename the xmldb_key.
      */
-
     public function getRenameKeySQL($xmldb_table, $xmldb_key, $newname) {
 
         $results = array();
@@ -861,7 +1003,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to add the index to the table
+     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to add the index to the table.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to add the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to add.
+     * @return array An array of SQL statements to add the index.
      */
     public function getAddIndexSQL($xmldb_table, $xmldb_index) {
 
@@ -870,7 +1016,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table
+     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to drop the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to drop.
+     * @return array An array of SQL statements to drop the index.
      */
     public function getDropIndexSQL($xmldb_table, $xmldb_index) {
 
@@ -891,6 +1041,11 @@ abstract class sql_generator {
     /**
      * Given one xmldb_table and one xmldb_index, return the SQL statements needed to rename the index in the table
      * Experimental! Shouldn't be used at all!
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to rename the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to rename.
+     * @param string $newname The xmldb_index's new name.
+     * @return array An array of SQL statements to rename the index.
      */
     function getRenameIndexSQL($xmldb_table, $xmldb_index, $newname) {
     /// Some DB doesn't support index renaming (MySQL) so this can be empty
@@ -914,6 +1069,11 @@ abstract class sql_generator {
      *
      * IMPORTANT: This function must be used to CALCULATE NAMES of objects TO BE CREATED,
      *            NEVER TO GUESS NAMES of EXISTING objects!!!
+     *
+     * @param string $tablename The table name.
+     * @param string $fields A list of comma separated fields.
+     * @param string $suffix A suffix for the object name.
+     * @return string Object's name.
      */
     public function getNameForObject($tablename, $fields, $suffix='') {
 
@@ -985,6 +1145,9 @@ abstract class sql_generator {
     /**
      * Given any string (or one array), enclose it by the proper quotes
      * if it's a reserved word
+     *
+     * @param string|array $input String to quote.
+     * @return Quoted string.
      */
     public function getEncQuoted($input) {
 
@@ -1005,7 +1168,10 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one XMLDB Statement, build the needed SQL insert sentences to execute it
+     * Given one XMLDB Statement, build the needed SQL insert sentences to execute it.
+     *
+     * @param string $statement SQL statement.
+     * @return array Array of sentences in the SQL statement.
      */
     function getExecuteInsertSQL($statement) {
 
@@ -1057,9 +1223,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one array of elements, build de proper CONCAT expression, based
+     * Given one array of elements, build the proper CONCAT expression, based
      * in the $concat_character setting. If such setting is empty, then
-     * MySQL's CONCAT function will be used instead
+     * MySQL's CONCAT function will be used instead.
+     *
+     * @param array $elements An array of elements to concatenate.
+     * @return mixed Returns the result of moodle_database::sql_concat() or false.
+     * @uses moodle_database::sql_concat()
+     * @uses call_user_func_array()
      */
     public function getConcatSQL($elements) {
 
@@ -1078,18 +1249,27 @@ abstract class sql_generator {
 
     /**
      * Returns the name (string) of the sequence used in the table for the autonumeric pk
-     * Only some DB have this implemented
+     * Only some DB have this implemented.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance.
+     * @return bool Returns the sequence from the DB or false.
      */
     public function getSequenceFromDB($xmldb_table) {
         return false;
     }
 
     /**
-     * Given one object name and it's type (pk, uk, fk, ck, ix, uix, seq, trg)
-     * return if such name is currently in use (true) or no (false)
+     * Given one object name and it's type (pk, uk, fk, ck, ix, uix, seq, trg).
+     *
      * (MySQL requires the whole xmldb_table object to be specified, so we add it always)
-     * (invoked from getNameForObject()
-     * Only some DB have this implemented
+     *
+     * This is invoked from getNameForObject().
+     * Only some DB have this implemented.
+     *
+     * @param string $object_name The object's name to check for.
+     * @param string $type The object's type (pk, uk, fk, ck, ix, uix, seq, trg).
+     * @param string $table_name The table's name to check in
+     * @return bool If such name is currently in use (true) or no (false)
      */
     public function isNameInUse($object_name, $type, $table_name) {
         return false; //For generators not implementing introspection,
@@ -1101,30 +1281,46 @@ abstract class sql_generator {
 
     /**
      * Reset a sequence to the id field of a table.
-     * @param string $table name of table
+     *
+     * @param string $tablename name of table.
      * @return success
      */
     public abstract function getResetSequenceSQL($tablename);
 
     /**
      * Given one correct xmldb_table, returns the SQL statements
-     * to create temporary table (inside one array)
+     * to create temporary table (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array SQL statements.
      */
     abstract public function getCreateTempTableSQL($xmldb_table);
 
     /**
-     * Given one correct xmldb_table and the new name, returns the SQL statements
-     * to drop it (inside one array)
+     * Given one correct xmldb_table and the new name, returns the SQL statements.
+     * to drop it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array SQL statements.
      */
     abstract public function getDropTempTableSQL($xmldb_table);
 
     /**
-     * Given one XMLDB Type, length and decimals, returns the DB proper SQL type
+     * Given one XMLDB Type, length and decimals, returns the DB proper SQL type.
+     *
+     * @param int $xmldb_type The xmldb_type defined constant. XMLDB_TYPE_INTEGER and other XMLDB_TYPE_* constants.
+     * @param int $xmldb_length The length of that data type.
+     * @param int $xmldb_decimals The decimal places of precision of the data type.
+     * @return string The DB defined data type.
      */
     public abstract function getTypeSQL($xmldb_type, $xmldb_length=null, $xmldb_decimals=null);
 
     /**
-     * Returns the code (array of statements) needed to execute extra statements on field rename
+     * Returns the code (array of statements) needed to execute extra statements on field rename.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     * @return array Array of extra SQL statements to run with a field being renamed.
      */
     public function getRenameFieldExtraSQL($xmldb_table, $xmldb_field) {
         return array();
@@ -1132,19 +1328,30 @@ abstract class sql_generator {
 
     /**
      * Returns the code (array of statements) needed
-     * to create one sequence for the xmldb_table and xmldb_field passes
+     * to create one sequence for the xmldb_table and xmldb_field passed in.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     * @return array Array of SQL statements to create the sequence.
      */
     public function getCreateSequenceSQL($xmldb_table, $xmldb_field) {
         return array();
     }
 
     /**
-     * Returns the code (array of statements) needed to add one comment to the table
+     * Returns the code (array of statements) needed to add one comment to the table.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array Array of SQL statements to add one comment to the table.
      */
     public abstract function getCommentSQL($xmldb_table);
 
     /**
-     * Returns the code (array of statements) needed to execute extra statements on table rename
+     * Returns the code (array of statements) needed to execute extra statements on table rename.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param string $newname The new name for the table.
+     * @return array Array of extra SQL statements to rename a table.
      */
     public function getRenameTableExtraSQL($xmldb_table, $newname) {
         return array();
@@ -1152,6 +1359,9 @@ abstract class sql_generator {
 
     /**
      * Returns the code (array of statements) needed to execute extra statements on table drop
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array Array of extra SQL statements to drop a table.
      */
     public function getDropTableExtraSQL($xmldb_table) {
         return array();
@@ -1161,7 +1371,12 @@ abstract class sql_generator {
      * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop its enum
      * (usually invoked from getModifyEnumSQL()
      *
-     * TODO: Moodle 2.1 - Drop getDropEnumSQL()
+     * Note that this method may be dropped in future.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     *
+     * @todo MDL-31147 Moodle 2.1 - Drop getDropEnumSQL()
      */
     public abstract function getDropEnumSQL($xmldb_table, $xmldb_field);
 
@@ -1169,7 +1384,12 @@ abstract class sql_generator {
      * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop its default
      * (usually invoked from getModifyDefaultSQL()
      *
-     * TODO: Moodle 2.1 - Drop getDropDefaultSQL()
+     * Note that this method may be dropped in future.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     *
+     * @todo MDL-31147 Moodle 2.1 - Drop getDropDefaultSQL()
      */
     public abstract function getDropDefaultSQL($xmldb_table, $xmldb_field);
 
@@ -1178,27 +1398,37 @@ abstract class sql_generator {
      * constrainst found for that table (or field). Must exist for each DB supported.
      * (usually invoked from find_check_constraint_name)
      *
-     * TODO: Moodle 2.1 - Drop getCheckConstraintsFromDB
+     * Note that this method may be dropped in future.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     *
+     * @todo MDL-31147 Moodle 2.1 - Drop getCheckConstraintsFromDB
      */
     public abstract function getCheckConstraintsFromDB($xmldb_table, $xmldb_field=null);
 
     /**
      * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add its default
      * (usually invoked from getModifyDefaultSQL()
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     * @return array Array of SQL statements to create a field's default.
      */
     public abstract function getCreateDefaultSQL($xmldb_table, $xmldb_field);
 
     /**
      * Returns an array of reserved words (lowercase) for this DB
-     * You MUST provide the real list for each DB inside every XMLDB class
-     * @return array of reserved words
+     * You MUST provide the real list for each DB inside every XMLDB class.
+     * @return array An array of database specific reserved words.
+     * @throws coding_exception Thrown if not implemented for the specific DB.
      */
     public static function getReservedWords() {
         throw new coding_exception('getReservedWords() method needs to be overridden in each subclass of sql_generator');
     }
 
     /**
-     * Returns all reserved works in supported databases.
+     * Returns all reserved words in supported databases.
      * Reserved words should be lowercase.
      * @return array ('word'=>array(databases))
      */
@@ -1219,6 +1449,11 @@ abstract class sql_generator {
         return $reserved_words;
     }
 
+    /**
+     * Adds slashes to string.
+     * @param string $s
+     * @return string The escaped string.
+     */
     public function addslashes($s) {
         // do not use php addslashes() because it depends on PHP quote settings!
         $s = str_replace('\\','\\\\',$s);
diff --git a/lib/ddl/sqlite_sql_generator.php b/lib/ddl/sqlite_sql_generator.php
index d2ba790b5a8..d190d070659 100644
--- a/lib/ddl/sqlite_sql_generator.php
+++ b/lib/ddl/sqlite_sql_generator.php
@@ -20,7 +20,7 @@
  * Experimental SQLite specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  2008 Andrei Bautu
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */