From dafa20e85c62a89749b9d265196e3892c3f77fbf Mon Sep 17 00:00:00 2001 From: Aparup Banerjee Date: Thu, 16 Feb 2012 10:29:45 +0800 Subject: [PATCH] MDL-30972 Documentation : improved @see as well as added appropriate uses of inline @link. --- lib/dml/moodle_database.php | 41 +++++++++++------------ lib/dml/mssql_native_moodle_database.php | 6 ++-- lib/dml/mysqli_native_moodle_database.php | 6 ++-- lib/dml/oci_native_moodle_database.php | 6 ++-- lib/dml/pdo_moodle_database.php | 6 ++-- lib/dml/pgsql_native_moodle_database.php | 6 ++-- lib/dml/sqlsrv_native_moodle_database.php | 6 ++-- lib/dmllib.php | 4 ++- 8 files changed, 47 insertions(+), 34 deletions(-) diff --git a/lib/dml/moodle_database.php b/lib/dml/moodle_database.php index e1a89941744..88309a42af1 100644 --- a/lib/dml/moodle_database.php +++ b/lib/dml/moodle_database.php @@ -60,7 +60,7 @@ define('SQL_QUERY_AUX', 5); /** * Abstract class representing moodle database interface. - * @See http://docs.moodle.org/dev/DML_functions + * @link http://docs.moodle.org/dev/DML_functions * * @package core * @category dml @@ -126,13 +126,11 @@ abstract class moodle_database { private $force_rollback = false; /** - * @var int internal temporary variable used to fix params. - * @see _fix_sql_params_dollar_callback() + * @var int internal temporary variable used to fix params. Its used by {@link _fix_sql_params_dollar_callback()}. */ private $fix_sql_params_i; /** - * @var int internal temporary variable used to guarantee unique parameters in each request. - * @see get_in_or_equal() + * @var int internal temporary variable used to guarantee unique parameters in each request. Its used by {@link get_in_or_equal()}. */ private $inorequaluniqueindex = 1; @@ -176,7 +174,7 @@ abstract class moodle_database { * @param string $type Database driver's type. (eg: mysqli, pgsql, mssql, sqldrv, oci, etc.) * @param string $library Database driver's library (native, pdo, etc.) * @param bool $external True if this is an external database. - * @return moodle_database driver object or null if error. for example @see mysqli_native_moodle_databases + * @return moodle_database driver object or null if error, for example of driver object see {@link mysqli_native_moodle_database} */ public static function get_driver_instance($type, $library, $external = false) { global $CFG; @@ -684,9 +682,8 @@ abstract class moodle_database { /** * Internal private utitlity function used to fix parameters. - * Used with preg_replace_callback() + * Used with {@link preg_replace_callback()} * @param array $match Refer to preg_replace_callback usage for description. - * @see preg_replace_callback() */ private function _fix_sql_params_dollar_callback($match) { $this->fix_sql_params_i++; @@ -889,7 +886,8 @@ abstract class moodle_database { /** * Returns the sql generator used for db manipulation. * Used mostly in upgrade.php scripts. - * @return database_manager The instance used to perform ddl operations. @see lib/ddl/database_manager.php + * @return database_manager The instance used to perform ddl operations. + * @see lib/ddl/database_manager.php */ public function get_manager() { global $CFG; @@ -1011,7 +1009,7 @@ abstract class moodle_database { * Only records where $field takes one of the values $values are returned. * $values must be an array of values. * - * Other arguments and the return type as for @see function get_recordset. + * Other arguments and the return type are like {@link function get_recordset}. * * @param string $table the table to query. * @param string $field a field to check (optional). @@ -1038,7 +1036,7 @@ abstract class moodle_database { * If given, $select is used as the SELECT parameter in the SQL query, * otherwise all records from the table are returned. * - * Other arguments and the return type as for @see function get_recordset. + * Other arguments and the return type are like {@link function get_recordset}. * * @param string $table the table to query. * @param string $select A fragment of SQL to be used in a where clause in the SQL call. @@ -1068,7 +1066,7 @@ abstract class moodle_database { * code where it's possible there might be large datasets being returned. For known * small datasets use get_records_sql - it leads to simpler code. * - * The return type is as for @see function get_recordset. + * The return type is like {@link function get_recordset}. * * @param string $sql the SQL select query to execute. * @param array $params array of sql parameters @@ -1107,7 +1105,7 @@ abstract class moodle_database { /** * Get a number of records as an array of objects where one field match one list of values. * - * Return value as for @see function get_records. + * Return value is like {@link function get_records}. * * @param string $table The database table to be checked against. * @param string $field The field to search @@ -1131,7 +1129,7 @@ abstract class moodle_database { /** * Get a number of records as an array of objects which match a particular WHERE clause. * - * Return value as for @see function get_records. + * Return value is like {@link function get_records}. * * @param string $table The table to query. * @param string $select A fragment of SQL to be used in a where clause in the SQL call. @@ -1158,7 +1156,7 @@ abstract class moodle_database { /** * Get a number of records as an array of objects using a SQL statement. * - * Return value as for @see function get_records. + * Return value is like {@link function get_records}. * * @param string $sql the SQL select query to execute. The first column of this SELECT statement * must be a unique value (usually the 'id' field), as it will be used as the key of the @@ -1174,7 +1172,7 @@ abstract class moodle_database { /** * Get the first two columns from a number of records as an associative array where all the given conditions met. * - * Arguments as for @see function get_recordset. + * Arguments are like {@link function get_recordset}. * * If no errors occur the return value * is an associative whose keys come from the first field of each record, @@ -1206,8 +1204,8 @@ abstract class moodle_database { /** * Get the first two columns from a number of records as an associative array which match a particular WHERE clause. * - * Arguments as for @see function get_recordset_select. - * Return value as for @see function get_records_menu. + * Arguments are like {@link function get_recordset_select}. + * Return value is like {@link function get_records_menu}. * * @param string $table The database table to be checked against. * @param string $select A fragment of SQL to be used in a where clause in the SQL call. @@ -1235,8 +1233,8 @@ abstract class moodle_database { /** * Get the first two columns from a number of records as an associative array using a SQL statement. * - * Arguments as for @see function get_recordset_sql. - * Return value as for @see function get_records_menu. + * Arguments are like {@link function get_recordset_sql}. + * Return value is like {@link function get_records_menu}. * * @param string $sql The SQL string you wish to be executed. * @param array $params array of sql parameters @@ -1861,7 +1859,8 @@ abstract class moodle_database { * * @deprecated since Moodle 2.0 MDL-23925 - please do not use this function any more. * @todo MDL-31280 to remove deprecated functions prior to 2.3 release. - * @return string Do not use this function! @see sql_like() + * @return string Do not use this function! + * @see sql_like() */ public function sql_ilike() { debugging('sql_ilike() is deprecated, please use sql_like() instead'); diff --git a/lib/dml/mssql_native_moodle_database.php b/lib/dml/mssql_native_moodle_database.php index d1ee7333055..59e69184f32 100644 --- a/lib/dml/mssql_native_moodle_database.php +++ b/lib/dml/mssql_native_moodle_database.php @@ -685,7 +685,8 @@ class mssql_native_moodle_database extends moodle_database { * code where it's possible there might be large datasets being returned. For known * small datasets use get_records_sql - it leads to simpler code. * - * The return type is as for @see function get_recordset. + * The return type is like: + * @see function get_recordset. * * @param string $sql the SQL select query to execute. * @param array $params array of sql parameters @@ -731,7 +732,8 @@ class mssql_native_moodle_database extends moodle_database { /** * Get a number of records as an array of objects using a SQL statement. * - * Return value as for @see function get_records. + * Return value is like: + * @see function get_records. * * @param string $sql the SQL select query to execute. The first column of this SELECT statement * must be a unique value (usually the 'id' field), as it will be used as the key of the diff --git a/lib/dml/mysqli_native_moodle_database.php b/lib/dml/mysqli_native_moodle_database.php index da9609adb1d..3f70beff41e 100644 --- a/lib/dml/mysqli_native_moodle_database.php +++ b/lib/dml/mysqli_native_moodle_database.php @@ -744,7 +744,8 @@ class mysqli_native_moodle_database extends moodle_database { * code where it's possible there might be large datasets being returned. For known * small datasets use get_records_sql - it leads to simpler code. * - * The return type is as for @see function get_recordset. + * The return type is like: + * @see function get_recordset. * * @param string $sql the SQL select query to execute. * @param array $params array of sql parameters @@ -784,7 +785,8 @@ class mysqli_native_moodle_database extends moodle_database { /** * Get a number of records as an array of objects using a SQL statement. * - * Return value as for @see function get_records. + * Return value is like: + * @see function get_records. * * @param string $sql the SQL select query to execute. The first column of this SELECT statement * must be a unique value (usually the 'id' field), as it will be used as the key of the diff --git a/lib/dml/oci_native_moodle_database.php b/lib/dml/oci_native_moodle_database.php index 807abdf1f5e..bc08fb947d0 100644 --- a/lib/dml/oci_native_moodle_database.php +++ b/lib/dml/oci_native_moodle_database.php @@ -1051,7 +1051,8 @@ class oci_native_moodle_database extends moodle_database { * code where it's possible there might be large datasets being returned. For known * small datasets use get_records_sql - it leads to simpler code. * - * The return type is as for @see function get_recordset. + * The return type is like: + * @see function get_recordset. * * @param string $sql the SQL select query to execute. * @param array $params array of sql parameters @@ -1083,7 +1084,8 @@ class oci_native_moodle_database extends moodle_database { /** * Get a number of records as an array of objects using a SQL statement. * - * Return value as for @see function get_records. + * Return value is like: + * @see function get_records. * * @param string $sql the SQL select query to execute. The first column of this SELECT statement * must be a unique value (usually the 'id' field), as it will be used as the key of the diff --git a/lib/dml/pdo_moodle_database.php b/lib/dml/pdo_moodle_database.php index ef2da313cb3..5f54613ce83 100644 --- a/lib/dml/pdo_moodle_database.php +++ b/lib/dml/pdo_moodle_database.php @@ -255,7 +255,8 @@ abstract class pdo_moodle_database extends moodle_database { * code where it's possible there might be large datasets being returned. For known * small datasets use get_records_sql - it leads to simpler code. * - * The return type is as for @see function get_recordset. + * The return type is like: + * @see function get_recordset. * * @param string $sql the SQL select query to execute. * @param array $params array of sql parameters @@ -308,7 +309,8 @@ abstract class pdo_moodle_database extends moodle_database { /** * Get a number of records as an array of objects. * - * Return value as for @see function get_records. + * Return value is like: + * @see function get_records. * * @param string $sql the SQL select query to execute. The first column of this SELECT statement * must be a unique value (usually the 'id' field), as it will be used as the key of the diff --git a/lib/dml/pgsql_native_moodle_database.php b/lib/dml/pgsql_native_moodle_database.php index 9e7df66858c..cdd1c5ecd4c 100644 --- a/lib/dml/pgsql_native_moodle_database.php +++ b/lib/dml/pgsql_native_moodle_database.php @@ -613,7 +613,8 @@ class pgsql_native_moodle_database extends moodle_database { * code where it's possible there might be large datasets being returned. For known * small datasets use get_records_sql - it leads to simpler code. * - * The return type is as for @see function get_recordset. + * The return type is like: + * @see function get_recordset. * * @param string $sql the SQL select query to execute. * @param array $params array of sql parameters @@ -653,7 +654,8 @@ class pgsql_native_moodle_database extends moodle_database { /** * Get a number of records as an array of objects using a SQL statement. * - * Return value as for @see function get_records. + * Return value is like: + * @see function get_records. * * @param string $sql the SQL select query to execute. The first column of this SELECT statement * must be a unique value (usually the 'id' field), as it will be used as the key of the diff --git a/lib/dml/sqlsrv_native_moodle_database.php b/lib/dml/sqlsrv_native_moodle_database.php index 757e6456c9b..a9386799030 100644 --- a/lib/dml/sqlsrv_native_moodle_database.php +++ b/lib/dml/sqlsrv_native_moodle_database.php @@ -752,7 +752,8 @@ class sqlsrv_native_moodle_database extends moodle_database { * code where it's possible there might be large datasets being returned. For known * small datasets use get_records_sql - it leads to simpler code. * - * The return type is as for @see function get_recordset. + * The return type is like: + * @see function get_recordset. * * @param string $sql the SQL select query to execute. * @param array $params array of sql parameters @@ -798,7 +799,8 @@ class sqlsrv_native_moodle_database extends moodle_database { /** * Get a number of records as an array of objects using a SQL statement. * - * Return value as for @see function get_records. + * Return value is like: + * @see function get_records. * * @param string $sql the SQL select query to execute. The first column of this SELECT statement * must be a unique value (usually the 'id' field), as it will be used as the key of the diff --git a/lib/dmllib.php b/lib/dmllib.php index 974b0f64288..005f30da4f0 100644 --- a/lib/dmllib.php +++ b/lib/dmllib.php @@ -281,7 +281,9 @@ class dml_transaction_exception extends dml_exception { /** * Sets up global $DB moodle_database instance * - * @global stdClass $CFG The global configuration instance. @see config.php @see config-dist.php + * @global stdClass $CFG The global configuration instance. + * @see config.php + * @see config-dist.php * @global stdClass $DB The global moodle_database instance. * @return void|bool Returns true when finished setting up $DB. Returns void when $DB has already been set. */