MDL-30972 Documentation : improved @see as well as added appropriate …

…uses of inline @link.

lib/dml/moodle_database.php

@@ -60,7 +60,7 @@
 
 /**
  * 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 @@ public function get_prefix() {
      * @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 @@ protected function fix_table_names($sql) {
 
     /**
      * 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 @@ public function reset_caches() {
     /**
      * 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 @@ public function get_recordset($table, array $conditions=null, $sort='', $fields=
      * 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 @@ public function get_recordset_list($table, $field, array $values, $sort='', $fie
      * 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 @@ public function get_recordset_select($table, $select, array $params=null, $sort=
      * 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 @@ public function get_records($table, array $conditions=null, $sort='', $fields='*
     /**
      * 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 @@ public function get_records_list($table, $field, array $values, $sort='', $field
     /**
      * 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 @@ public function get_records_select($table, $select, array $params=null, $sort=''
     /**
      * 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 @@ public abstract function get_records_sql($sql, array $params=null, $limitfrom=0,
     /**
      * 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 @@ public function get_records_menu($table, array $conditions=null, $sort='', $fiel
     /**
      * 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 @@ public function get_records_select_menu($table, $select, array $params=null, $so
     /**
      * 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 @@ public function sql_like_escape($text, $escapechar = '\\') {
      *
      * @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');

lib/dml/mssql_native_moodle_database.php

@@ -685,7 +685,8 @@ public function execute($sql, array $params=null) {
      * 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 @@ protected function create_recordset($result) {
     /**
      * 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

lib/dml/mysqli_native_moodle_database.php

@@ -744,7 +744,8 @@ public function execute($sql, array $params=null) {
      * 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 @@ protected function create_recordset($result) {
     /**
      * 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

lib/dml/oci_native_moodle_database.php

@@ -1051,7 +1051,8 @@ public function get_record_sql($sql, array $params=null, $strictness=IGNORE_MISS
      * 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 @@ protected function create_recordset($stmt) {
     /**
      * 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

lib/dml/pdo_moodle_database.php

@@ -255,7 +255,8 @@ public function execute($sql, array $params=null) {
      * 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 @@ public function get_fieldset_sql($sql, array $params=null) {
     /**
      * 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

lib/dml/pgsql_native_moodle_database.php

@@ -613,7 +613,8 @@ public function execute($sql, array $params=null) {
      * 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 @@ protected function create_recordset($result) {
     /**
      * 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

lib/dml/sqlsrv_native_moodle_database.php

@@ -752,7 +752,8 @@ public function execute($sql, array $params = null) {
      * 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 @@ protected function create_recordset($result) {
     /**
      * 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

lib/dmllib.php

@@ -281,7 +281,9 @@ function __construct($debuginfo=null, $transaction=null) {
 /**
  * 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.
  */