MDL-63020 xmldb: Improve PHPdoc comments for better IDE autocomplete

lib/ddl/sql_generator.php

@@ -1129,7 +1129,7 @@ abstract class sql_generator {
      * if it's a reserved word
      *
      * @param string|array $input String to quote.
-     * @return string Quoted string.
+     * @return string|array Quoted string.
      */
     public function getEncQuoted($input) {
 

lib/ddl/tests/ddl_test.php

@@ -26,8 +26,10 @@
 defined('MOODLE_INTERNAL') || die();
 
 class core_ddl_testcase extends database_driver_testcase {
+    /** @var xmldb_table[] keys are table name. Created in setUp. */
     private $tables = array();
-    private $records= array();
+    /** @var array table name => array of stdClass test records loaded into that table. Created in setUp. */
+    private $records = array();
 
     protected function setUp() {
         parent::setUp();

lib/dml/moodle_database.php

@@ -1080,7 +1080,7 @@ abstract class moodle_database {
      * Returns detailed information about columns in table. This information is cached internally.
      * @param string $table The table's name.
      * @param bool $usecache Flag to use internal cacheing. The default is true.
-     * @return array of database_column_info objects indexed with column names
+     * @return database_column_info[] of database_column_info objects indexed with column names
      */
     public abstract function get_columns($table, $usecache=true);
 

lib/xmldb/xmldb_index.php

@@ -338,7 +338,7 @@ class xmldb_index extends xmldb_object {
      */
     public function validateDefinition(xmldb_table $xmldb_table=null) {
         if (!$xmldb_table) {
-            return 'Invalid xmldb_index->validateDefinition() call, $xmldb_table si required.';
+            return 'Invalid xmldb_index->validateDefinition() call, $xmldb_table is required.';
         }
 
         $total = 0;

lib/xmldb/xmldb_table.php

@@ -28,13 +28,13 @@ defined('MOODLE_INTERNAL') || die();
 
 class xmldb_table extends xmldb_object {
 
-    /** @var array table columns */
+    /** @var xmldb_field[] table columns */
     protected $fields;
 
-    /** @var array keys */
+    /** @var xmldb_key[] keys */
     protected $keys;
 
-    /** @var array indexes */
+    /** @var xmldb_index[] indexes */
     protected $indexes;
 
     /**
@@ -239,7 +239,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will return the array of fields in the table
-     * @return array
+     * @return xmldb_field[]
      */
     public function getFields() {
         return $this->fields;
@@ -247,7 +247,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will return the array of keys in the table
-     * @return array
+     * @return xmldb_key[]
      */
     public function getKeys() {
         return $this->keys;
@@ -255,7 +255,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will return the array of indexes in the table
-     * @return array
+     * @return xmldb_index[]
      */
     public function getIndexes() {
         return $this->indexes;
@@ -264,7 +264,7 @@ class xmldb_table extends xmldb_object {
     /**
      * Returns one xmldb_field
      * @param string $fieldname
-     * @return mixed
+     * @return xmldb_field|null
      */
     public function getField($fieldname) {
         $i = $this->findFieldInArray($fieldname);
@@ -277,7 +277,7 @@ class xmldb_table extends xmldb_object {
     /**
      * Returns the position of one field in the array.
      * @param string $fieldname
-     * @return mixed
+     * @return int|null index of the field, or null if not found.
      */
     public function findFieldInArray($fieldname) {
         foreach ($this->fields as $i => $field) {
@@ -290,7 +290,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will reorder the array of fields
-     * @return bool
+     * @return bool whether the reordering succeeded.
      */
     public function orderFields() {
         $result = $this->orderElements($this->fields);
@@ -305,7 +305,7 @@ class xmldb_table extends xmldb_object {
     /**
      * Returns one xmldb_key
      * @param string $keyname
-     * @return mixed
+     * @return xmldb_key|null
      */
     public function getKey($keyname) {
         $i = $this->findKeyInArray($keyname);
@@ -318,7 +318,7 @@ class xmldb_table extends xmldb_object {
     /**
      * Returns the position of one key in the array.
      * @param string $keyname
-     * @return mixed
+     * @return int|null index of the key, or null if not found.
      */
     public function findKeyInArray($keyname) {
         foreach ($this->keys as $i => $key) {
@@ -331,7 +331,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will reorder the array of keys
-     * @return bool
+     * @return bool whether the reordering succeeded.
      */
     public function orderKeys() {
         $result = $this->orderElements($this->keys);
@@ -346,7 +346,7 @@ class xmldb_table extends xmldb_object {
     /**
      * Returns one xmldb_index
      * @param string $indexname
-     * @return mixed
+     * @return xmldb_index|null
      */
     public function getIndex($indexname) {
         $i = $this->findIndexInArray($indexname);
@@ -359,7 +359,7 @@ class xmldb_table extends xmldb_object {
     /**
      * Returns the position of one index in the array.
      * @param string $indexname
-     * @return mixed
+     * @return int|null index of the index, or null if not found.
      */
     public function findIndexInArray($indexname) {
         foreach ($this->indexes as $i => $index) {
@@ -372,7 +372,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will reorder the array of indexes
-     * @return bool
+     * @return bool whether the reordering succeeded.
      */
     public function orderIndexes() {
         $result = $this->orderElements($this->indexes);
@@ -386,7 +386,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will set the array of fields in the table
-     * @param array $fields
+     * @param xmldb_field[] $fields
      */
     public function setFields($fields) {
         $this->fields = $fields;
@@ -394,7 +394,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will set the array of keys in the table
-     * @param array $keys
+     * @param xmldb_key[] $keys
      */
     public function setKeys($keys) {
         $this->keys = $keys;
@@ -402,7 +402,7 @@ class xmldb_table extends xmldb_object {
 
     /**
      * This function will set the array of indexes in the table
-     * @param array $indexes
+     * @param xmldb_index[] $indexes
      */
     public function setIndexes($indexes) {
         $this->indexes = $indexes;