Merge branch 'wip-mdl-25432' of git://github.com/rajeshtaneja/moodle
authorEloy Lafuente (stronk7) <stronk7@moodle.org>
Tue, 21 Feb 2012 01:10:10 +0000 (02:10 +0100)
committerEloy Lafuente (stronk7) <stronk7@moodle.org>
Tue, 21 Feb 2012 01:10:10 +0000 (02:10 +0100)
213 files changed:
admin/mnet/peer_forms.php
backup/moodle2/restore_stepslib.php
blog/rsslib.php
enrol/ldap/lang/en/enrol_ldap.php
grade/edit/letter/edit_form.php
grade/edit/letter/index.php
grade/edit/letter/tabs.php
grade/edit/outcome/course.php
grade/edit/outcome/edit.php
grade/edit/outcome/edit_form.php
grade/edit/outcome/export.php
grade/edit/outcome/import.php
grade/edit/outcome/import_outcomes_form.php
grade/edit/outcome/index.php
grade/edit/outcome/tabs.php
grade/edit/scale/edit.php
grade/edit/scale/edit_form.php
grade/edit/scale/index.php
grade/edit/settings/form.php
grade/edit/settings/index.php
grade/edit/tree/action.php
grade/edit/tree/calculation.php
grade/edit/tree/calculation_form.php
grade/edit/tree/category.php
grade/edit/tree/category_form.php
grade/edit/tree/grade.php
grade/edit/tree/grade_form.php
grade/edit/tree/index.php
grade/edit/tree/item.php
grade/edit/tree/item_form.php
grade/edit/tree/lib.php
grade/edit/tree/outcomeitem.php
grade/edit/tree/outcomeitem_form.php
grade/grading/form/rubric/styles.css
grade/grading/manage.php
grade/grading/pick.php
grade/index.php
grade/lib.php
grade/querylib.php
grade/report/grader/ajax_callbacks.php
grade/report/grader/db/access.php
grade/report/grader/index.php
grade/report/grader/lang/en/gradereport_grader.php
grade/report/grader/lib.php
grade/report/grader/preferences.php
grade/report/grader/preferences_form.php
grade/report/grader/quickedit_item.php
grade/report/grader/settings.php
grade/report/grader/tabs.php
grade/report/grader/version.php
grade/report/index.php
grade/report/lib.php
grade/report/outcomes/db/access.php
grade/report/outcomes/index.php
grade/report/outcomes/lang/en/gradereport_outcomes.php
grade/report/outcomes/version.php
grade/report/overview/db/access.php
grade/report/overview/index.php
grade/report/overview/lang/en/gradereport_overview.php
grade/report/overview/lib.php
grade/report/overview/renderer.php
grade/report/overview/settings.php
grade/report/overview/version.php
grade/report/user/db/access.php
grade/report/user/index.php
grade/report/user/lang/en/gradereport_user.php
grade/report/user/lib.php
grade/report/user/renderer.php
grade/report/user/settings.php
grade/report/user/version.php
lang/en/langconfig.php
lang/en/mnet.php
lib/ajax/ajaxlib.php
lib/ajax/setuserpref.php
lib/db/install.xml
lib/db/upgrade.php
lib/dml/database_column_info.php
lib/dml/moodle_database.php
lib/dml/moodle_recordset.php
lib/dml/moodle_temptables.php
lib/dml/moodle_transaction.php
lib/dml/mssql_native_moodle_database.php
lib/dml/mssql_native_moodle_recordset.php
lib/dml/mssql_native_moodle_temptables.php
lib/dml/mysqli_native_moodle_database.php
lib/dml/mysqli_native_moodle_recordset.php
lib/dml/mysqli_native_moodle_temptables.php
lib/dml/oci_native_moodle_database.php
lib/dml/oci_native_moodle_package.sql
lib/dml/oci_native_moodle_recordset.php
lib/dml/oci_native_moodle_temptables.php
lib/dml/pdo_moodle_database.php
lib/dml/pdo_moodle_recordset.php
lib/dml/pgsql_native_moodle_database.php
lib/dml/pgsql_native_moodle_recordset.php
lib/dml/pgsql_native_moodle_temptables.php
lib/dml/sqlite3_pdo_moodle_database.php
lib/dml/sqlsrv_native_moodle_database.php
lib/dml/sqlsrv_native_moodle_recordset.php
lib/dml/sqlsrv_native_moodle_temptables.php
lib/dmllib.php
lib/form/advcheckbox.php
lib/form/button.php
lib/form/cancel.php
lib/form/checkbox.php
lib/form/dateselector.php
lib/form/datetimeselector.php
lib/form/duration.php
lib/form/editor.php
lib/form/file.php
lib/form/filemanager.php
lib/form/filepicker.php
lib/form/format.php
lib/form/grading.php
lib/form/group.php
lib/form/header.php
lib/form/hidden.php
lib/form/htmleditor.php
lib/form/modgrade.php
lib/form/modvisible.php
lib/form/password.php
lib/form/passwordunmask.php
lib/form/questioncategory.php
lib/form/radio.php
lib/form/recaptcha.php
lib/form/searchableselector.php
lib/form/select.php
lib/form/selectgroups.php
lib/form/selectwithlink.php
lib/form/selectyesno.php
lib/form/simpletest/testduration.php
lib/form/static.php
lib/form/submit.php
lib/form/submitlink.php
lib/form/tags.php
lib/form/text.php
lib/form/textarea.php
lib/form/url.php
lib/form/warning.php
lib/formslib.php
lib/grade/constants.php
lib/grade/grade_category.php
lib/grade/grade_grade.php
lib/grade/grade_item.php
lib/grade/grade_object.php
lib/grade/grade_outcome.php
lib/grade/grade_scale.php
lib/grade/simpletest/testgradecategory.php
lib/grade/simpletest/testgradegrades.php
lib/grade/simpletest/testgradeitem.php
lib/grade/simpletest/testgradeoutcome.php
lib/grade/simpletest/testgradescale.php
lib/gradelib.php
lib/moodlelib.php
lib/outputactions.php
lib/outputcomponents.php
lib/outputfactories.php
lib/outputlib.php
lib/outputrenderers.php
lib/outputrequirementslib.php
lib/pagelib.php
lib/pluginlib.php
lib/rsslib.php
lib/simpletest/testmoodlelib.php
message/index.php
mnet/peer.php
mod/assignment/grade.php
mod/assignment/lib.php
mod/assignment/type/upload/assignment.class.php
mod/assignment/type/uploadsingle/assignment.class.php
mod/data/lib.php
mod/data/rsslib.php
mod/forum/lib.php
mod/forum/rsslib.php
mod/glossary/db/install.xml
mod/glossary/db/upgrade.php
mod/glossary/formats/entrylist/entrylist_format.php
mod/glossary/lang/en/glossary.php
mod/glossary/lib.php
mod/glossary/mod_form.php
mod/glossary/rsslib.php
mod/glossary/showentry.php
mod/glossary/version.php
mod/glossary/view.php
mod/lesson/backup/moodle2/restore_lesson_stepslib.php
mod/lesson/grade.php
mod/lesson/lib.php
mod/lti/lib.php
mod/quiz/grade.php
mod/quiz/lib.php
mod/scorm/datamodels/debug.js.php
mod/scorm/datamodels/scorm_datamodels.js [deleted file]
mod/scorm/grade.php
mod/scorm/lang/en/scorm.php
mod/scorm/lib.php
mod/scorm/locallib.php
mod/scorm/mod_form.php
mod/scorm/module.js
mod/scorm/report/basic/report.php
mod/scorm/report/interactions/report.php
mod/scorm/styles.css
mod/workshop/lib.php
repository/filepicker.js
rss/file.php
rss/renderer.php
theme/afterburner/style/afterburner_layout.css
theme/arialist/style/settings.css
theme/standard/style/core.css
version.php
webservice/lib.php
webservice/rest/locallib.php
webservice/rest/server.php
webservice/soap/locallib.php

index 4e2e173..4c5243b 100644 (file)
@@ -98,6 +98,7 @@ class mnet_review_host_form extends moodleform {
 
         $mform->addElement('textarea', 'public_key', get_string('publickey', 'mnet'), array('rows' => 17, 'cols' => 100, 'class' => 'smalltext'));
         $mform->setType('public_key', PARAM_PEM);
+        $mform->addRule('public_key', get_string('required'), 'required');
 
         // finished with form controls, now the static informational stuff
         if ($mnet_peer && !empty($mnet_peer->bootstrapped)) {
@@ -160,7 +161,9 @@ class mnet_review_host_form extends moodleform {
         }
         $mnet_peer = new mnet_peer(); // idiotic api
         $mnet_peer->wwwroot = $data['wwwroot']; // just hard-set this rather than bootstrap the object
-        if (!$credentials = $mnet_peer->check_credentials($data['public_key'])) {
+        if (empty($data['public_key'])) {
+            $errors['public_key'] = get_string('publickeyrequired', 'mnet');
+        } else if (!$credentials = $mnet_peer->check_credentials($data['public_key'])) {
             $errmsg = '';
             foreach ($mnet_peer->error as $err) {
                 $errmsg .= $err['code'] . ': ' . $err['text'].'<br />';
index 2aebdcf..acf17be 100644 (file)
@@ -1124,6 +1124,12 @@ class restore_course_structure_step extends restore_structure_step {
             unset($data->idnumber);
         }
 
+        // Any empty value for course->hiddensections will lead to 0 (default, show collapsed).
+        // It has been reported that some old 1.9 courses may have it null leading to DB error. MDL-31532
+        if (empty($data->hiddensections)) {
+            $data->hiddensections = 0;
+        }
+
         // Only restrict modules if original course was and target site too for new courses
         $data->restrictmodules = $data->restrictmodules && !empty($CFG->restrictmodulesfor) && $CFG->restrictmodulesfor == 'all';
 
index 03c84ca..a851cbe 100644 (file)
@@ -1,8 +1,41 @@
 <?php
 
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Blog RSS Management
+ *
+ * @package    core_blog
+ * @category   rss
+ * @copyright  2010 Andrew Davis
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 require_once($CFG->dirroot.'/lib/rsslib.php');
 require_once($CFG->dirroot .'/blog/lib.php');
 
+/**
+ * Build the URL for the RSS feed
+ *
+ * @param int    $contextid    The context under which the URL should be created
+ * @param int    $userid       The id of the user requesting the RSS Feed
+ * @param string $filtertype   The source of the RSS feed (site/course/group/user)
+ * @param int    $filterselect The id of the item defined by $filtertype
+ * @param int    $tagid        The id of the row in the tag table that identifies the RSS Feed
+ * @return string
+ */
 function blog_rss_get_url($contextid, $userid, $filtertype, $filterselect=0, $tagid=0) {
     $componentname = 'blog';
 
@@ -29,8 +62,15 @@ function blog_rss_get_url($contextid, $userid, $filtertype, $filterselect=0, $ta
     return rss_get_url($contextid, $userid, $componentname, $additionalargs);
 }
 
-// This function returns the icon (from theme) with the link to rss/file.php
-// needs some hacking to rss/file.php
+/**
+ * Print the link for the RSS feed with the correct RSS icon (Theme based)
+ *
+ * @param stdClass    $context      The context under which the URL should be created
+ * @param string      $filtertype   The source of the RSS feed (site/course/group/user)
+ * @param int         $filterselect The id of the item defined by $filtertype
+ * @param int         $tagid        The id of the row in the tag table that identifies the RSS Feed
+ * @param string      $tooltiptext  The tooltip to be displayed with the link
+ */
 function blog_rss_print_link($context, $filtertype, $filterselect=0, $tagid=0, $tooltiptext='') {
     global $CFG, $USER, $OUTPUT;
 
@@ -45,6 +85,15 @@ function blog_rss_print_link($context, $filtertype, $filterselect=0, $tagid=0, $
     print '<div class="mdl-right"><a href="'. $url .'"><img src="'. $rsspix .'" title="'. strip_tags($tooltiptext) .'" alt="'.get_string('rss').'" /></a></div>';
 }
 
+/**
+ * Build the URL for the RSS feed amd add it as a header
+ *
+ * @param stdClass    $context      The context under which the URL should be created
+ * @param string      $title        Name for the link to be added to the page header
+ * @param string      $filtertype   The source of the RSS feed (site/course/group/user)
+ * @param int         $filterselect The id of the item defined by $filtertype
+ * @param int         $tagid        The id of the row in the tag table that identifies the RSS Feed
+ */
 function blog_rss_add_http_header($context, $title, $filtertype, $filterselect=0, $tagid=0) {
     global $PAGE, $USER, $CFG;
 
@@ -63,8 +112,9 @@ function blog_rss_add_http_header($context, $title, $filtertype, $filterselect=0
 
 /**
  * Utility function to extract parameters needed to generate RSS URLs from the blog filters
- * @param <type> $filters
- * @return array array containing the id of the user/course/group, the relevant context and the filter type (site/user/course/group)
+ *
+ * @param  array $filters filters for the blog
+ * @return array array containing the id of the user/course/group, the relevant context and the filter type: site/user/course/group
  */
 function blog_rss_get_params($filters) {
     $thingid = $rsscontext = $filtertype = null;
@@ -99,8 +149,12 @@ function blog_rss_get_params($filters) {
     return array($thingid, $rsscontext, $filtertype);
 }
 
-
-// Generate any blog RSS feed via one function (called by ../rss/file.php)
+/**
+ * Generate any blog RSS feed via one function
+ *
+ * @param stdClass $context The context of the blog for which the feed it being generated
+ * @param array    $args    An array of arguements needed to build the feed (contextid, token, componentname, type, id, tagid)
+ */
 function blog_rss_get_feed($context, $args) {
     global $CFG, $SITE, $DB;
 
@@ -219,7 +273,14 @@ function blog_rss_get_feed($context, $args) {
     }
 }
 
-
+/**
+ * Retrieve the location and file name of a cached RSS feed
+ *
+ * @param string $type  The source of the RSS feed (site/course/group/user)
+ * @param int    $id    The id of the item defined by $type
+ * @param int    $tagid The id of the row in the tag table that identifies the RSS Feed
+ * @return string
+ */
 function blog_rss_file_name($type, $id, $tagid=0) {
     global $CFG;
 
@@ -230,7 +291,15 @@ function blog_rss_file_name($type, $id, $tagid=0) {
     }
 }
 
-//This function saves to file the rss feed specified in the parameters
+/**
+ * This function saves to file the rss feed specified in the parameters
+ *
+ * @param string $type     The source of the RSS feed (site/course/group/user)
+ * @param int    $id       The id of the item defined by $type
+ * @param int    $tagid    The id of the row in the tag table that identifies the RSS Feed
+ * @param string $contents The contents of the RSS Feed file
+ * @return bool whether the save was successful or not
+ */
 function blog_rss_save_file($type, $id, $tagid=0, $contents='') {
     global $CFG;
 
index aa92c84..df3b34f 100644 (file)
@@ -92,7 +92,7 @@ $string['phpldap_noextension'] = '<em>The PHP LDAP module does not seem to be pr
 $string['pluginname'] = 'LDAP enrolments';
 $string['pluginname_desc'] = '<p>You can use an LDAP server to control your enrolments. It is assumed your LDAP tree contains groups that map to the courses, and that each of those groups/courses will have membership entries to map to students.</p><p>It is assumed that courses are defined as groups in LDAP, with each group having multiple membership fields (<em>member</em> or <em>memberUid</em>) that contain a uniqueidentification of the user.</p><p>To use LDAP enrolment, your users <strong>must</strong> to have a valid  idnumber field. The LDAP groups must have that idnumber in the member fields for a user to be enrolled in the course. This will usually work well if you are already using LDAP Authentication.</p><p>Enrolments will be updated when the user logs in. You can also run a script to keep enrolments in synch. Look in <em>enrol/ldap/cli/sync.php</em>.</p><p>This plugin can also be set to automatically create new courses when new groups appear in LDAP.</p>';
 $string['pluginnotenabled'] = 'Plugin not enabled!';
-$string['role_mapping'] = '<p>For each rol that you want to assign from LDAP, you need to specify the list of contexts where the role courses\'s groups are located. Separate different contexts with \';\'.</p><p>You also need to specify the attribute your LDAP server uses to hold the members of a group. Usually \'member\' or \'memberUid\'</p>';
+$string['role_mapping'] = '<p>For each role that you want to assign from LDAP, you need to specify the list of contexts where the role courses\'s groups are located. Separate different contexts with \';\'.</p><p>You also need to specify the attribute your LDAP server uses to hold the members of a group. Usually \'member\' or \'memberUid\'</p>';
 $string['role_mapping_key'] = 'Map roles from LDAP ';
 $string['roles'] = 'Role mapping';
 $string['server_settings'] = 'LDAP server settings';
index 9931484..baa4087 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A moodleform for editing grade letters
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index e0a2904..d0dc35a 100644 (file)
@@ -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
@@ -18,7 +17,7 @@
 /**
  * List of grade letters.
  *
- * @package   moodlecore
+ * @package   core_grades
  * @copyright 2008 Nicolas Connault
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index e87dbb3..a67fa96 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Prints navigation tabs for viewing and editing grade letters
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
     $row = $tabs = array();
 
     $row[] = new tabobject('lettersview',
index 63462f1..d23b002 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A page for selecting outcomes for use in a course
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->libdir.'/gradelib.php';
index 1f4d9b7..d273289 100644 (file)
@@ -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
@@ -18,7 +17,7 @@
 /**
  * Edit page for grade outcomes.
  *
- * @package   moodlecore
+ * @package   core_grades
  * @copyright 2008 Nicolas Connault
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 6c1893e..fe2c682 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Edit form for grade outcomes
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index dbb510f..154db68 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-      // Exports selected outcomes in CSV format.
+/**
+ * Exports selected outcomes in CSV format
+ *
+ * @package   core_grades
+ * @copyright 2008 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
index 6e62867..b212877 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Import outcomes from a file
+ *
+ * @package   core_grades
+ * @copyright 2008 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once(dirname(__FILE__).'/../../../config.php');
 require_once($CFG->dirroot.'/lib/formslib.php');
 require_once($CFG->dirroot.'/grade/lib.php');
index f6077c8..4a263c8 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A form to allow importing outcomes from a file
+ *
+ * @package   core_grades
+ * @copyright 2008 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index 45915b2..f8df7d8 100644 (file)
@@ -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
@@ -18,7 +17,7 @@
 /**
  * Listing page for grade outcomes.
  *
- * @package   moodlecore
+ * @package   core_grades
  * @copyright 2008 Nicolas Connault
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 23355bd..50da663 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Prints navigation tabs for viewing and editing grade outcomes
+ *
+ * @package   core_grades
+ * @copyright 2009 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
     $row = $tabs = array();
 
     $coursecontext = get_context_instance(CONTEXT_COURSE, $courseid);
index f226139..ee633c6 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Edit page for grade scales
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->dirroot.'/grade/report/lib.php';
index db75e8e..fa6af48 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Edit form for grade scales
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index 237944e..7063feb 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A page for managing custom and standard scales
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->libdir.'/gradelib.php';
index 5d541e7..6c9df49 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A form for editing course grade settings
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index c4949a4..0ac15f6 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A page for editing course grade settings
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->libdir.'/gradelib.php';
index ed8d2af..c350dd4 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Performs actions on grade items and categories like hiding and locking
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 
index 9993324..89d5cd2 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Edit a calculated grade item
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->libdir.'/mathslib.php';
index 5ba7af9..fc5e088 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A moodleform to allow the editing of a calculated grade item
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index 0c37f8c..100369a 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Edit the grade options for an individual grade category
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->dirroot.'/grade/report/lib.php';
index aec1dea..5a1d8f7 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A moodleform to edit the grade options for an individual grade category
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index ab188de..53fc1ee 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Edit a user's grade for a particular activity
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->dirroot.'/grade/report/lib.php';
index 440146a..a184226 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A moodleform to allow the editing of a user's grade for a particular activity
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index 8d88615..801c9ef 100644 (file)
@@ -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
@@ -16,9 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Edit and review page for grade categories and items.
+ * Edit and review page for grade categories and items
  *
- * @package   moodlecore
+ * @package   core_grades
  * @copyright 2008 Nicolas Connault
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 1ce936c..5b2a7c0 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Edit the grade options for an individual grade item
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->dirroot.'/grade/report/lib.php';
index 642be6b..6dd9683 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A moodleform allowing the editing of the grade options for an individual grade item
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index 49af487..6057831 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A library of classes used by the grade edit pages
+ *
+ * @package   core_grades
+ * @copyright 2009 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 class grade_edit_tree {
     public $columns = array();
 
index 518f111..3112d41 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A page to create or edit outcome grade items
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->dirroot.'/grade/lib.php';
 require_once $CFG->dirroot.'/grade/report/lib.php';
index 4cd5a71..3442599 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * A moodleform to allow the creation and editing of outcome grade items
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
index b88df4e..4d8e705 100644 (file)
@@ -49,6 +49,8 @@
 .gradingform_rubric_editform .status.ready {background-color:#e7f1c3;border-color:#AAEEAA;}
 .gradingform_rubric_editform .status.draft {background-color:#f3f2aa;border-color:#EEEE22;}
 
+.gradingform_rubric {overflow:auto;padding-bottom:1.5em;max-width:720px;position:relative;}
+
 .gradingform_rubric.editor .criterion .controls,
 .gradingform_rubric .criterion .description,
 .gradingform_rubric .criterion .levels,
index 7ccefa9..954f91f 100644 (file)
@@ -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
@@ -22,7 +21,7 @@
  * area, provides access to the plugin editor and allows user to save the
  * current form as a template or re-use some existing form.
  *
- * @package    core
+ * @package    core_grades
  * @subpackage grading
  * @copyright  2011 David Mudrak <david@moodle.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index 779e95c..d140cd6 100644 (file)
@@ -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
@@ -18,7 +17,7 @@
 /**
  * Allows to choose a form from the list of available templates
  *
- * @package    core
+ * @package    core_grades
  * @subpackage grading
  * @copyright  2011 David Mudrak <david@moodle.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index 4e9f80e..b2d0b65 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-/*
- * Compatibility redirection to reports
+/**
+ * This page is provided for compatability and redirects the user to the default grade report
+ *
+ * @package   core_grades
+ * @copyright 2005 onwards Martin Dougiamas  {@link http://moodle.com}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once '../config.php';
index 25071d2..8c969f2 100644 (file)
@@ -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
@@ -18,7 +17,7 @@
 /**
  * Functions used by gradebook plugins and reports.
  *
- * @package   moodlecore
+ * @package   core_grades
  * @copyright 2009 Petr Skoda and Nicolas Connault
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -563,7 +562,7 @@ function grade_get_plugin_info($courseid, $active_type, $active_plugin) {
  * A simple class containing info about grade plugins.
  * Can be subclassed for special rules
  *
- * @package moodlecore
+ * @package core_grades
  * @copyright 2009 Nicolas Connault
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -694,7 +693,7 @@ function print_grade_page_head($courseid, $active_type, $active_plugin=null,
 /**
  * Utility class used for return tracking when using edit and other forms in grade plugins
  *
- * @package moodlecore
+ * @package core_grades
  * @copyright 2009 Nicolas Connault
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -1000,7 +999,7 @@ function grade_build_nav($path, $pagename=null, $id=null) {
 /**
  * General structure representing grade items in course
  *
- * @package moodlecore
+ * @package core_grades
  * @copyright 2009 Nicolas Connault
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -1557,7 +1556,7 @@ class grade_structure {
  * Flat structure similar to grade tree.
  *
  * @uses grade_structure
- * @package moodlecore
+ * @package core_grades
  * @copyright 2009 Nicolas Connault
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -1694,7 +1693,7 @@ class grade_seq extends grade_structure {
  * deletion and moving of items and categories within the tree.
  *
  * @uses grade_structure
- * @package moodlecore
+ * @package core_grades
  * @copyright 2009 Nicolas Connault
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index b66756a..6cf9763 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Returns the aggregated or calculated course grade(s) in given course.
- * @public
- * @param int $courseid id of course
- * @param int $userid_or_ids optional id of the graded user or array of ids; if userid not used, returns only information about grade_item
- * @return information about course grade item scaleid, name, grade and locked status, etc. + user grades
+ * Functions used to retrieve grades objects
+ *
+ * @package   core_grades
+ * @category  grade
+ * @copyright 2008 Petr Skoda and Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Returns the aggregated or calculated course grade(s) for a single course for one or more users
+ *
+ * @param int $courseid The ID of course
+ * @param int|array $userid_or_ids Optional ID of the graded user or array of user IDs; if userid not used, returns only information about grade_item
+ * @return stdClass Returns an object containing information about course grade item. scaleid, name, grade
+ *         and locked status etc and user course grades: $item->grades[$userid] => $usercoursegrade
  */
 function grade_get_course_grades($courseid, $userid_or_ids=null) {
 
@@ -118,10 +127,10 @@ function grade_get_course_grades($courseid, $userid_or_ids=null) {
 }
 
 /**
- * Returns the aggregated or calculated course grade for the given user(s).
- * @public
- * @param int $userid
- * @param int $courseid optional id of course or array of ids, empty means all uses courses (returns array if not present)
+ * Returns the aggregated or calculated course grade for a single user for one or more courses
+ *
+ * @param int $userid The ID of the single user
+ * @param int|array $courseid_or_ids Optional ID of course or array of IDs, empty means all of the user's courses
  * @return mixed grade info or grades array including item info, false if error
  */
 function grade_get_course_grade($userid, $courseid_or_ids=null) {
@@ -233,8 +242,9 @@ function grade_get_course_grade($userid, $courseid_or_ids=null) {
 /**
  * Returns all grade items (including outcomes) or main item for a given activity identified by $cm object.
  *
- * @param object $cm A course module object (preferably with modname property)
- * @return mixed - array of grade item instances (one if $only_main_item true), false if error or not found
+ * @param cm_info $cm A course module object (preferably with modname property)
+ * @param bool $only_main_item Limit the search to the primary grade item for the activity, 'itemnumber'==0
+ * @return mixed An array of grade item instances, one grade item if $only_main_item == true, false if error or not found
  */
 function grade_get_grade_items_for_activity($cm, $only_main_item=false) {
     global $CFG, $DB;
@@ -261,11 +271,11 @@ function grade_get_grade_items_for_activity($cm, $only_main_item=false) {
 }
 
 /**
- * Returns whether or not user received grades in main grade item for given activity.
+ * Returns whether or not a user received grades in main grade item for given activity
  *
- * @param object $cm
- * @param int $userid
- * @return bool True if graded false if user not graded yet
+ * @param cm_info $cm The activity context module
+ * @param int $userid The user ID
+ * @return bool True if graded, false if user not graded yet
  */
 function grade_is_user_graded_in_activity($cm, $userid) {
 
index 463f1d6..e374510 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * This file receives ajax callbacks for the grader report
+ *
+ * @package   gradereport_grader
+ * @copyright 2008 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 require_once '../../../config.php';
 require_once $CFG->libdir.'/gradelib.php';
index 41715d8..9859577 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Capability definition for the gradebook grader report
+ *
+ * @package   gradereport_grader
+ * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 $capabilities = array(
 
     'gradereport/grader:view' => array(
index 3a35fd8..6cbaff1 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * The gradebook grader report
+ *
+ * @package   gradereport_grader
+ * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->libdir.'/gradelib.php';
 require_once $CFG->dirroot.'/grade/lib.php';
index 435f28b..d59dfdd 100644 (file)
@@ -16,7 +16,7 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Strings for component 'gradereport_grader', language 'en', branch 'MOODLE_20_STABLE'
+ * Strings for component 'gradereport_grader', language 'en'
  *
  * @package   gradereport_grader
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
index 7c9fb38..5771195 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * File in which the grader_report class is defined.
- * @package gradebook
+ * Definition of the grader report class
+ *
+ * @package   gradereport_grader
+ * @copyright 2007 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once($CFG->dirroot . '/grade/report/lib.php');
@@ -26,7 +28,7 @@ require_once($CFG->libdir.'/tablelib.php');
 /**
  * Class providing an API for the grader report building and displaying.
  * @uses grade_report
- * @package gradebook
+ * @package gradereport_grader
  */
 class grade_report_grader extends grade_report {
     /**
index 595eb84..0bac965 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Grader report preferences configuration page
+ *
+ * @package   gradereport_grader
+ * @copyright 2007 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 set_time_limit(0);
 require_once '../../../config.php';
 require_once $CFG->libdir . '/gradelib.php';
index 93f4c03..ff41d39 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-
 /**
- * Form for grader report preferences.
+ * Form for grader report preferences
  *
- * @package    moodlecore
- * @subpackage grade
+ * @package    gradereport_grader
  * @copyright  2009 Nicolas Connault
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 7a9ce65..ac720c2 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Allow the editing of grades for a grade item
+ *
+ * @package   gradereport_grader
+ * @copyright 2009 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->libdir.'/gradelib.php';
 require_once $CFG->dirroot.'/grade/lib.php';
index c795b33..7220870 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Defines site config settings for the grader report
+ *
+ * @package    gradereport_grader
+ * @copyright  2007 Moodle Pty Ltd (http://moodle.com)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 defined('MOODLE_INTERNAL') || die;
 
 if ($ADMIN->fulltree) {
index c1e4d40..610c594 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Outputs navigation tabs for the grader report
+ *
+ * @package   gradereport_grader
+ * @copyright 2007 2009 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
     $row = $tabs = array();
     $tabcontext = get_context_instance(CONTEXT_COURSE, $COURSE->id);
     $row[] = new tabobject('graderreport',
index 14c2e50..93ff8e6 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Version details
+ * Version details for the grader report
  *
- * @package    gradereport
- * @subpackage grader
+ * @package    gradereport_grader
  * @copyright  1999 onwards Martin Dougiamas (http://dougiamas.com)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index e4ba906..43aaf66 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Redirects the user to the default grade report
+ *
+ * @package   core_grades
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../config.php';
 
 $courseid = required_param('id', PARAM_INT);
index a49b89e..2475550 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * File containing the grade_report class.
- * @package gradebook
+ * File containing the grade_report class
+ *
+ * @package   core_grades
+ * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once($CFG->libdir.'/gradelib.php');
 
 /**
  * An abstract class containing variables and methods used by all or most reports.
- * @abstract
- * @package gradebook
+ * @package core_grades
  */
 abstract class grade_report {
     /**
index d37fa82..a4dcba6 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Defines capabilities for the outcomes report
+ *
+ * @package   gradereport_outcomes
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 $capabilities = array(
 
     'gradereport/outcomes:view' => array(
index cf73c63..ab49694 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * The gradebook outcomes report
+ *
+ * @package   gradereport_outcomes
+ * @copyright 2007 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 include_once('../../../config.php');
 require_once($CFG->libdir . '/gradelib.php');
 require_once $CFG->dirroot.'/grade/lib.php';
index e82830e..9cc0633 100644 (file)
@@ -16,7 +16,7 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Strings for component 'gradereport_outcomes', language 'en', branch 'MOODLE_20_STABLE'
+ * Strings for component 'gradereport_outcomes', language 'en'
  *
  * @package   gradereport_outcomes
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
index d70dc07..9bc1637 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Version details
+ * Version details for the outcomes report
  *
- * @package    gradereport
- * @subpackage outcomes
+ * @package    gradereport_outcomes
  * @copyright  1999 onwards Martin Dougiamas (http://dougiamas.com)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 3e29f06..6843f94 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Defines capabilities for the overview report
+ *
+ * @package   gradereport_overview
+ * @copyright 2007 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 $capabilities = array(
 
     'gradereport/overview:view' => array(
index fefc771..a1134c7 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * The gradebook overview report
+ *
+ * @package   gradereport_overview
+ * @copyright 2007 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->libdir.'/gradelib.php';
 require_once $CFG->dirroot.'/grade/lib.php';
index 0cf91b9..7829783 100644 (file)
@@ -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
@@ -16,7 +15,7 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Strings for component 'gradereport_overview', language 'en', branch 'MOODLE_20_STABLE'
+ * Strings for component 'gradereport_overview', language 'en'
  *
  * @package   gradereport_overview
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
index b610817..0cd8ff4 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * File in which the overview_report class is defined.
- * @package gradebook
+ * Definition of the grade_overview_report class
+ *
+ * @package gradereport_overview
+ * @copyright 2007 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once($CFG->dirroot . '/grade/report/lib.php');
@@ -26,7 +28,7 @@ require_once($CFG->libdir.'/tablelib.php');
 /**
  * Class providing an API for the overview report building and displaying.
  * @uses grade_report
- * @package gradebook
+ * @package gradereport_overview
  */
 class grade_report_overview extends grade_report {
 
index 7de6733..1090d2f 100644 (file)
@@ -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
@@ -16,9 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Renderer for the grade user report
+ * Renderer for the gradebook overview report
  *
- * @package   moodlecore
+ * @package   gradereport_overview
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -44,4 +43,4 @@ class gradereport_overview_renderer extends plugin_renderer_base {
         return $output;
     }
 
-}
\ No newline at end of file
+}
index d994637..c1e43d8 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-/// Add settings for this module to the $settings object (it's already defined)
+/**
+ * Defines site settings for the overview gradebook report
+ *
+ * @package gradereport_overview
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 defined('MOODLE_INTERNAL') || die;
 
index 80d7b71..c7761e9 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Version details
+ * Version details for the overview gradebook report
  *
- * @package    gradereport
- * @subpackage overview
+ * @package    gradereport_overview
  * @copyright  1999 onwards Martin Dougiamas (http://dougiamas.com)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index d19d468..ac07dbb 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Defines capabilities for the user report
+ *
+ * @package   gradereport_user
+ * @copyright 2007 onwards Martin Dougiamas (http://dougiamas.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 $capabilities = array(
 
     'gradereport/user:view' => array(
index 10aeffb..e15c4fb 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * The gradebook user report
+ *
+ * @package   gradereport_user
+ * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once '../../../config.php';
 require_once $CFG->libdir.'/gradelib.php';
 require_once $CFG->dirroot.'/grade/lib.php';
index 0ba1725..70da1b1 100644 (file)
@@ -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
@@ -16,7 +15,7 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Strings for component 'gradereport_user', language 'en', branch 'MOODLE_20_STABLE'
+ * Strings for component 'gradereport_user', language 'en'
  *
  * @package   gradereport_user
  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
index bc93369..9e823cf 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * File in which the user_report class is defined.
- * @package gradebook
+ * Definition of the grade_user_report class is defined
+ *
+ * @package gradereport_user
+ * @copyright 2007 Nicolas Connault
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once($CFG->dirroot . '/grade/report/lib.php');
@@ -31,7 +33,7 @@ define("GRADE_REPORT_USER_SHOW_HIDDEN", 2);
 /**
  * Class providing an API for the user report building and displaying.
  * @uses grade_report
- * @package gradebook
+ * @package gradereport_user
  */
 class grade_report_user extends grade_report {
 
index 1e4b083..c0270f3 100644 (file)
@@ -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
@@ -18,7 +17,7 @@
 /**
  * Renderer for the grade user report
  *
- * @package   moodlecore
+ * @package   gradereport_user
  * @copyright 2010 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -44,4 +43,4 @@ class gradereport_user_renderer extends plugin_renderer_base {
         return $output;
     }
 
-}
\ No newline at end of file
+}
index 5d53534..d469f68 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-/// Add settings for this module to the $settings object (it's already defined)
+/**
+ * Defines site settings for the user gradebook report
+ *
+ * @package gradereport_user
+ * @copyright 2007 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 defined('MOODLE_INTERNAL') || die;
 
index 6532800..2250edb 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Version details
+ * Version details for the user gradebook report
  *
- * @package    gradereport
- * @subpackage user
+ * @package    gradereport_user
  * @copyright  1999 onwards Martin Dougiamas (http://dougiamas.com)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 4da2ea8..7905f66 100644 (file)
@@ -39,16 +39,16 @@ $string['parentlanguage'] = '';
 $string['strftimedate'] = '%d %B %Y';
 $string['strftimedatefullshort'] = '%d/%m/%y';
 $string['strftimedateshort'] = '%d %B';
-$string['strftimedatetime'] = '%d %B %Y, %l:%M %p';
+$string['strftimedatetime'] = '%d %B %Y, %I:%M %p';
 $string['strftimedatetimeshort'] = '%d/%m/%y, %H:%M';
 $string['strftimedaydate'] = '%A, %d %B %Y';
-$string['strftimedaydatetime'] = '%A, %d %B %Y, %l:%M %p';
+$string['strftimedaydatetime'] = '%A, %d %B %Y, %I:%M %p';
 $string['strftimedayshort'] = '%A, %d %B';
 $string['strftimedaytime'] = '%a, %H:%M';
 $string['strftimemonthyear'] = '%B %Y';
 $string['strftimerecent'] = '%d %b, %H:%M';
-$string['strftimerecentfull'] = '%a, %d %b %Y, %l:%M %p';
-$string['strftimetime'] = '%l:%M %p';
+$string['strftimerecentfull'] = '%a, %d %b %Y, %I:%M %p';
+$string['strftimetime'] = '%I:%M %p';
 $string['thisdirection'] = 'ltr';
 $string['thisdirectionvertical'] = 'btt';
 $string['thislanguage'] = 'English';
index f087849..36cd958 100644 (file)
@@ -179,6 +179,7 @@ $string['profileimportfields'] = 'Fields to import';
 $string['promiscuous'] = 'Promiscuous';
 $string['publickey'] = 'Public key';
 $string['publickey_help'] = 'The public key is automatically obtained from the remote server.';
+$string['publickeyrequired'] = 'You must provide a public key.';
 $string['publish'] = 'Publish';
 $string['reallydeleteserver'] = 'Are you sure you want to delete the server';
 $string['receivedwarnings'] = 'The following warnings were received';
index f7d378f..0060cfd 100644 (file)
@@ -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
  */
 
 /**
- * You need to call this function if you wish to use the set_user_preference
- * method in javascript_static.php, to white-list the preference you want to update
- * from JavaScript, and to specify the type of cleaning you expect to be done on
- * values.
+ * You need to call this function if you wish to use the set_user_preference method in javascript_static.php, to white-list the
+ * preference you want to update from JavaScript, and to specify the type of cleaning you expect to be done on values.
  *
- * @param string $name the name of the user_perference we should allow to be
- *      updated by remote calls.
- * @param integer $paramtype one of the PARAM_{TYPE} constants, user to clean
- *      submitted values before set_user_preference is called.
- * @return void
+ * @package  core
+ * @category preference
+ * @param    string          $name      the name of the user_perference we should allow to be updated by remote calls.
+ * @param    integer         $paramtype one of the PARAM_{TYPE} constants, user to clean submitted values before set_user_preference is called.
+ * @return   null
  */
 function user_preference_allow_ajax_update($name, $paramtype) {
     global $USER, $PAGE;
index ca94ccb..d4b819d 100644 (file)
@@ -1,35 +1,29 @@
 <?php
-
-///////////////////////////////////////////////////////////////////////////
-//                                                                       //
-// NOTICE OF COPYRIGHT                                                   //
-//                                                                       //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
-//          http://moodle.org                                            //
-//                                                                       //
-// Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
-//                                                                       //
-// This program is free software; you can redistribute it and/or modify  //
-// it under the terms of the GNU General Public License as published by  //
-// the Free Software Foundation; either version 2 of the License, or     //
-// (at your option) any later version.                                   //
-//                                                                       //
-// This program is distributed in the hope that it will be useful,       //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
-// GNU General Public License for more details:                          //
-//                                                                       //
-//          http://www.gnu.org/copyleft/gpl.html                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Code to update a user preference in response to an ajax call. You should not
- * send requests to this script directly. Instead use the set_user_preference
+ * Code to update a user preference in response to an ajax call.
+ *
+ * You should not send requests to this script directly. Instead use the set_user_preference
  * function in javascript_static.js.
  *
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package moodlecore
+ * @package    core
+ * @category   preference
+ * @copyright  2008 Tim Hunt
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once(dirname(__FILE__) . '/../../config.php');
index 657814d..81c5a91 100644 (file)
         <FIELD NAME="subject" TYPE="char" LENGTH="128" NOTNULL="true" SEQUENCE="false" PREVIOUS="coursemoduleid" NEXT="summary"/>
         <FIELD NAME="summary" TYPE="text" LENGTH="big" NOTNULL="false" SEQUENCE="false" PREVIOUS="subject" NEXT="content"/>
         <FIELD NAME="content" TYPE="text" LENGTH="big" NOTNULL="false" SEQUENCE="false" PREVIOUS="summary" NEXT="uniquehash"/>
-        <FIELD NAME="uniquehash" TYPE="char" LENGTH="128" NOTNULL="true" SEQUENCE="false" PREVIOUS="content" NEXT="rating"/>
+        <FIELD NAME="uniquehash" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" PREVIOUS="content" NEXT="rating"/>
         <FIELD NAME="rating" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="uniquehash" NEXT="format"/>
         <FIELD NAME="format" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="rating" NEXT="summaryformat"/>
         <FIELD NAME="summaryformat" TYPE="int" LENGTH="2" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="format" NEXT="attachment"/>
index 2c28ba3..df9b3f8 100644 (file)
@@ -145,6 +145,48 @@ function xmldb_main_upgrade($oldversion) {
         upgrade_main_savepoint(true, 2012020200.06);
     }
 
+    if ($oldversion < 2012021700.01) {
+        // Changing precision of field uniquehash on table post to 255
+        $table = new xmldb_table('post');
+        $field = new xmldb_field('uniquehash', XMLDB_TYPE_CHAR, '255', null, XMLDB_NOTNULL, null, null, 'content');
+
+        // Launch change of precision for field uniquehash
+        $dbman->change_field_precision($table, $field);
+
+        // Main savepoint reached
+        upgrade_main_savepoint(true, 2012021700.01);
+    }
+
+    if ($oldversion < 2012021700.02) {
+        // Somewhere before 1.9 summary and content column in post table were not null. In 1.9+
+        // not null became false.
+        $columns = $DB->get_columns('post');
+
+        // Fix discrepancies in summary field after upgrade from 1.9
+        if (array_key_exists('summary', $columns) && $columns['summary']->not_null != false) {
+            $table = new xmldb_table('post');
+            $summaryfield = new xmldb_field('summary', XMLDB_TYPE_TEXT, 'big', null, null, null, null, 'subject');
+
+            if ($dbman->field_exists($table, $summaryfield)) {
+                $dbman->change_field_notnull($table, $summaryfield);
+            }
+
+        }
+
+        // Fix discrepancies in content field after upgrade from 1.9
+        if (array_key_exists('content', $columns) && $columns['content']->not_null != false) {
+            $table = new xmldb_table('post');
+            $contentfield = new xmldb_field('content', XMLDB_TYPE_TEXT, 'big', null, null, null, null, 'summary');
+
+            if ($dbman->field_exists($table, $contentfield)) {
+                $dbman->change_field_notnull($table, $contentfield);
+            }
+
+        }
+
+        upgrade_main_savepoint(true, 2012021700.02);
+    }
+
     return true;
 }
 
index e7e1987..a6c762a 100644 (file)
@@ -20,6 +20,7 @@
  * Database column information.
  *
  * @package    core
+ * @category   dml
  * @subpackage dml
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * Detail database field information.
- * Based on ADOFieldObject.
+ * Detailed database field information.
+ *
+ * It is based on the adodb library's ADOFieldObject object.
+ * 'column' does mean 'the field' here.
+ *
+ * @package core
+ * @category dml
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class database_column_info {
     /**
-     * Name of column - lowercase
+     * Name of column - lowercase.
+     * @var string
      */
     public $name;
 
     /**
-     * Driver dependent native data type
-     * Not standardised - used to find meta_type
+     * Driver dependent native data type.
+     * Not standardised, its used to find meta_type.
+     * @var string
      */
     public $type;
 
@@ -51,6 +61,7 @@ class database_column_info {
      *  float - digits left from floating point
      *  boolean - 1
      *  enums - null
+     * @var int
      */
     public $max_length;
 
@@ -58,6 +69,7 @@ class database_column_info {
      * Scale
      * float - decimal points
      * other - null
+     * @var int
      */
     public $scale;
 
@@ -67,54 +79,63 @@ class database_column_info {
      *
      * For performance reasons this field is optional!
      * You can use DDL sql_generator::getCheckConstraintsFromDB() if needed.
+     * @var string
      */
     public $enums;
 
     /**
      * True if not null, false otherwise
+     * @var bool
      */
     public $not_null;
 
     /**
      * True if column is primary key.
      * (usually 'id').
+     * @var bool
      */
     public $primary_key;
 
     /**
      * True if filed autoincrementing
      * (usually 'id' only)
+     * @var bool
      */
     public $auto_increment;
 
     /**
      * True if binary
+     * @var bool
      */
     public $binary;
 
     /**
      * True if integer unsigned, false if signed.
      * Null for other types
+     * @var integer
      */
     public $unsigned;
 
     /**
-     * True if default value defined
+     * True if the default value is defined.
+     * @var bool
      */
     public $has_default;
 
     /**
-     * Default value if defined
+     * The default value (if defined).
+     * @var string
      */
     public $default_value;
 
     /**
-     * True if field values unique, false if not
+     * True if field values are unique, false if not.
+     * @var bool
      */
     public $unique;
 
     /**
-     * Standardised one character column type, uppercase
+     * Standardised one character column type, uppercased and enumerated as follows:
      * R - counter (integer primary key)
      * I - integers
      * N - numbers (floats)
@@ -124,12 +145,13 @@ class database_column_info {
      * L - boolean (1 bit)
      * T - timestamp - unsupported
      * D - date - unsupported
+     * @var string
      */
     public $meta_type;
 
     /**
      * Constructor
-     * @param $data mixed object or array with properties
+     * @param mixed $data object or array with properties
      */
     public function __construct($data) {
         foreach ($data as $key=>$value) {
index 6e00b4c..88309a4 100644 (file)
 /**
  * Abstract database driver class.
  *
- * @package    core
+ * @package core
+ * @category dml
  * @subpackage dml
- * @copyright  2008 Petr Skoda (http://skodak.org)
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -33,61 +34,66 @@ require_once($CFG->libdir.'/dml/moodle_transaction.php');
 
 /// GLOBAL CONSTANTS /////////////////////////////////////////////////////////
 
-/** Bitmask, indicates :name type parameters are supported by db backend. */
+/** SQL_PARAMS_NAMED - Bitmask, indicates :name type parameters are supported by db backend. */
 define('SQL_PARAMS_NAMED', 1);
 
-/** Bitmask, indicates ? type parameters are supported by db backend. */
+/** SQL_PARAMS_QM - Bitmask, indicates ? type parameters are supported by db backend. */
 define('SQL_PARAMS_QM', 2);
 
-/** Bitmask, indicates $1, $2, ... type parameters are supported by db backend. */
+/** SQL_PARAMS_DOLLAR - Bitmask, indicates $1, $2, ... type parameters are supported by db backend. */
 define('SQL_PARAMS_DOLLAR', 4);
 
-
-/** Normal select query, reading only */
+/** SQL_QUERY_SELECT - Normal select query, reading only. */
 define('SQL_QUERY_SELECT', 1);
 
-/** Insert select query, writing */
+/** SQL_QUERY_INSERT - Insert select query, writing. */
 define('SQL_QUERY_INSERT', 2);
 
-/** Update select query, writing */
+/** SQL_QUERY_UPDATE - Update select query, writing. */
 define('SQL_QUERY_UPDATE', 3);
 
-/** Query changing db structure, writing */
+/** SQL_QUERY_STRUCTURE - Query changing db structure, writing. */
 define('SQL_QUERY_STRUCTURE', 4);
 
-/** Auxiliary query done by driver, setting connection config, getting table info, etc. */
+/** SQL_QUERY_AUX - Auxiliary query done by driver, setting connection config, getting table info, etc. */
 define('SQL_QUERY_AUX', 5);
 
 /**
  * Abstract class representing moodle database interface.
+ * @link http://docs.moodle.org/dev/DML_functions
+ *
+ * @package    core
+ * @category   dml
+ * @copyright  2008 Petr Skoda (http://skodak.org)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class moodle_database {
 
-    /** @var database_manager db manager which allows db structure modifications */
+    /** @var database_manager db manager which allows db structure modifications. */
     protected $database_manager;
-    /** @var moodle_temptables temptables manager to provide cross-db support for temp tables */
+    /** @var moodle_temptables temptables manager to provide cross-db support for temp tables. */
     protected $temptables;
-    /** @var array cache of column info */
+    /** @var array Cache of column info. */
     protected $columns = array(); // I wish we had a shared memory cache for this :-(
-    /** @var array cache of table info */
+    /** @var array Cache of table info. */
     protected $tables  = null;
 
     // db connection options
-    /** @var string db host name */
+    /** @var string db host name. */
     protected $dbhost;
-    /** @var string db host user */
+    /** @var string db host user. */
     protected $dbuser;
-    /** @var string db host password */
+    /** @var string db host password. */
     protected $dbpass;
-    /** @var string db name */
+    /** @var string db name. */
     protected $dbname;
-    /** @var string table prefix */
+    /** @var string Prefix added to table names. */
     protected $prefix;
 
-    /** @var array Database or driver specific options, such as sockets or TCPIP db connections */
+    /** @var array Database or driver specific options, such as sockets or TCPIP db connections. */
     protected $dboptions;
 
-    /** @var bool true means non-moodle external database used.*/
+    /** @var bool True means non-moodle external database used.*/
     protected $external;
 
     /** @var int The database reads (performance counter).*/
@@ -95,39 +101,43 @@ abstract class moodle_database {
     /** @var int The database writes (performance counter).*/
     protected $writes = 0;
 
-    /** @var int Debug level */
+    /** @var int Debug level. */
     protected $debug  = 0;
 
-    /** @var string last query sql */
+    /** @var string Last used query sql. */
     protected $last_sql;
-    /** @var array last query parameters */
+    /** @var array Last query parameters. */
     protected $last_params;
-    /** @var int last query type */
+    /** @var int Last query type. */
     protected $last_type;
-    /** @var string last extra info */
+    /** @var string Last extra info. */
     protected $last_extrainfo;
-    /** @var float last time in seconds with millisecond precision */
+    /** @var float Last time in seconds with millisecond precision. */
     protected $last_time;
-    /** @var bool flag indicating logging of query in progress, prevents infinite loops */
+    /** @var bool Flag indicating logging of query in progress. This helps prevent infinite loops. */
     private $loggingquery = false;
 
-    /** @var bool true if db used for db sessions */
+    /** @var bool True if the db is used for db sessions. */
     protected $used_for_db_sessions = false;
 
-    /** @var array open transactions */
+    /** @var array Array containing open transactions. */
     private $transactions = array();
-    /** @var bool force rollback of all current transactions */
+    /** @var bool Flag used to force rollback of all current transactions. */
     private $force_rollback = false;
 
-    /** @var int internal temporary variable */
+    /**
+     * @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 by {@link get_in_or_equal()}. */
-    private $inorequaluniqueindex = 1; // guarantees unique parameters in each request
+    /**
+     * @var int internal temporary variable used to guarantee unique parameters in each request. Its used by {@link get_in_or_equal()}.
+     */
+    private $inorequaluniqueindex = 1;
 
     /**
-     * Constructor - instantiates the database, specifying if it's external (connect to other systems) or no (Moodle DB)
-     *              note this has effect to decide if prefix checks must be performed or no
-     * @param bool true means external database used
+     * Constructor - Instantiates the database, specifying if it's external (connect to other systems) or not (Moodle DB).
+     *              Note that this affects the decision of whether prefix checks must be performed or not.
+     * @param bool $external True means that an external database is used.
      */
     public function __construct($external=false) {
         $this->external  = $external;
@@ -141,16 +151,16 @@ abstract class moodle_database {
     }
 
     /**
-     * Detects if all needed PHP stuff installed.
+     * Detects if all needed PHP stuff are installed for DB connectivity.
      * Note: can be used before connect()
-     * @return mixed true if ok, string if something
+     * @return mixed True if requirements are met, otherwise a string if something isn't installed.
      */
     public abstract function driver_installed();
 
     /**
      * Returns database table prefix
      * Note: can be used before connect()
-     * @return string database table prefix
+     * @return string The prefix used in the database.
      */
     public function get_prefix() {
         return $this->prefix;
@@ -158,10 +168,13 @@ abstract class moodle_database {
 
     /**
      * Loads and returns a database instance with the specified type and library.
-     * @param string $type database type of the driver (mysqli, pgsql, mssql, sqldrv, oci, etc.)
-     * @param string $library database library of the driver (native, pdo, etc.)
-     * @param boolean $external true if this is an external database
-     * @return moodle_database driver object or null if error
+     *
+     * The loaded class is within lib/dml directory and of the form: $type.'_'.$library.'_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 of driver object see {@link mysqli_native_moodle_database}
      */
     public static function get_driver_instance($type, $library, $external = false) {
         global $CFG;
@@ -178,50 +191,50 @@ abstract class moodle_database {
     }
 
     /**
-     * Returns database family type - describes SQL dialect
+     * Returns the database family type. (This sort of describes the SQL 'dialect')
      * Note: can be used before connect()
-     * @return string db family name (mysql, postgres, mssql, oracle, etc.)
+     * @return string The db family name (mysql, postgres, mssql, oracle, etc.)
      */
     public abstract function get_dbfamily();
 
     /**
-     * Returns more specific database driver type
+     * Returns more specific database driver type
      * Note: can be used before connect()
-     * @return string db type mysqli, pgsql, oci, mssql, sqlsrv
+     * @return string The db type mysqli, pgsql, oci, mssql, sqlsrv
      */
     protected abstract function get_dbtype();
 
     /**
-     * Returns general database library name
+     * Returns the general database library name
      * Note: can be used before connect()
-     * @return string db type pdo, native
+     * @return string The db library type -  pdo, native etc.
      */
     protected abstract function get_dblibrary();
 
     /**
-     * Returns localised database type name
+     * Returns the localised database type name
      * Note: can be used before connect()
      * @return string
      */
     public abstract function get_name();
 
     /**
-     * Returns localised database configuration help.
+     * Returns the localised database configuration help.
      * Note: can be used before connect()
      * @return string
      */
     public abstract function get_configuration_help();
 
     /**
-     * Returns localised database description
+     * Returns the localised database description
      * Note: can be used before connect()
      * @return string
      */
     public abstract function get_configuration_hints();
 
     /**
-     * Returns db related part of config.php
-     * @return object
+     * Returns the db related part of config.php
+     * @return stdClass
      */
     public function export_dbconfig() {
         $cfg = new stdClass();
@@ -250,12 +263,12 @@ abstract class moodle_database {
     }
 
     /**
-     * Connect to db
+     * Connects to the database.
      * Must be called before other methods.
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database user to connect as.
+     * @param string $dbpass The password to use when connecting to the database.
+     * @param string $dbname The name of the database being connected to.
      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return bool true
@@ -265,10 +278,10 @@ abstract class moodle_database {
 
     /**
      * Store various database settings
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database user to connect as.
+     * @param string $dbpass The password to use when connecting to the database.
+     * @param string $dbname The name of the database being connected to.
      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return void
@@ -284,19 +297,20 @@ abstract class moodle_database {
 
     /**
      * Attempt to create the database
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database user to connect as.
+     * @param string $dbpass The password to use when connecting to the database.
+     * @param string $dbname The name of the database being connected to.
+     * @param array $dboptions An array of optional database options (eg: dbport)
      *
-     * @return bool success
+     * @return bool success True for successful connection. False otherwise.
      */
     public function create_database($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null) {
         return false;
     }
 
     /**
-     * Close database connection and release all resources
+     * Closes the database connection and releases all resources
      * and memory (especially circular memory references).
      * Do NOT use connect() again, create a new instance if needed.
      * @return void
@@ -331,11 +345,11 @@ abstract class moodle_database {
     }
 
     /**
-     * Called before each db query.
-     * @param string $sql
-     * @param array array of parameters
-     * @param int $type type of query
-     * @param mixed $extrainfo driver specific extra information
+     * This should be called before each db query.
+     * @param string $sql The query string.
+     * @param array $params An array of parameters.
+     * @param int $type The type of query. ( SQL_QUERY_SELECT | SQL_QUERY_AUX | SQL_QUERY_INSERT | SQL_QUERY_UPDATE | SQL_QUERY_STRUCTURE )
+     * @param mixed $extrainfo This is here for any driver specific extra information.
      * @return void
      */
     protected function query_start($sql, array $params=null, $type, $extrainfo=null) {
@@ -363,8 +377,10 @@ abstract class moodle_database {
     }
 
     /**
-     * Called immediately after each db query.
-     * @param mixed db specific result
+     * This should be called immediately after each db query. It does a clean up of resources.
+     * It also throws exceptions if the sql that ran produced errors.
+     * @param mixed $result The db specific result obtained from running a query.
+     * @throws dml_read_exception | dml_write_exception | ddl_change_structure_exception
      * @return void
      */
     protected function query_end($result) {
@@ -402,7 +418,7 @@ abstract class moodle_database {
     }
 
     /**
-     * Log last database query if requested
+     * This logs the last query based on 'logall', 'logslow' and 'logerrors' options configured via $CFG->dboptions .
      * @param mixed string error or false if not error
      * @return void
      */
@@ -444,27 +460,27 @@ abstract class moodle_database {
 
     /**
      * Returns database server info array
-     * @return array
+     * @return array Array containing 'description' and 'version' atleast.
      */
     public abstract function get_server_info();
 
     /**
      * Returns supported query parameter types
-     * @return int bitmask
+     * @return int bitmask of accepted SQL_PARAMS_*
      */
     protected abstract function allowed_param_types();
 
     /**
-     * Returns last error reported by database engine.
-     * @return string error message
+     * Returns the last error reported by the database engine.
+     * @return string The error message.
      */
     public abstract function get_last_error();
 
     /**
-     * Print sql debug info
-     * @param string $sql query which caused problems
-     * @param array $params optional query parameters
-     * @param mixed $obj optional library specific object
+     * Prints sql debug info
+     * @param string $sql The query which is being debugged.
+     * @param array $params The query parameters. (optional)
+     * @param mixed $obj The library specific object. (optional)
      * @return void
      */
     protected function print_debug($sql, array $params=null, $obj=null) {
@@ -489,10 +505,11 @@ abstract class moodle_database {
     }
 
     /**
-     * Returns SQL WHERE conditions.
-     * @param string $table - the table name that these conditions will be validated against.
-     * @param array conditions - must not contain numeric indexes
-     * @return array sql part and params
+     * Returns the SQL WHERE conditions.
+     * @param string $table The table name that these conditions will be validated against.
+     * @param array $conditions The conditions to build the where clause. (must not contain numeric indexes)
+     * @throws dml_exception
+     * @return array An array list containing sql 'where' part and 'params'.
      */
     protected function where_clause($table, array $conditions=null) {
         // We accept nulls in conditions
@@ -553,11 +570,11 @@ abstract class moodle_database {
     }
 
     /**
-     * Returns SQL WHERE conditions for the ..._list methods.
+     * Returns SQL WHERE conditions for the ..._list group of methods.
      *
      * @param string $field the name of a field.
      * @param array $values the values field might take.
-     * @return array sql part and params
+     * @return array An array containing sql 'where' part and 'params'
      */
     protected function where_clause_list($field, array $values) {
         $params = array();
@@ -579,14 +596,15 @@ abstract class moodle_database {
     }
 
     /**
-     * Constructs IN() or = sql fragment
-     * @param mixed $items single or array of values
-     * @param int $type bound param type SQL_PARAMS_QM or SQL_PARAMS_NAMED
-     * @param string $prefix named parameter placeholder prefix (unique counter value is appended to each parameter name)
-     * @param bool $equal true means equal, false not equal
-     * @param mixed $onemptyitems defines the behavior when the array of items is empty. Defaults to false,
+     * Constructs 'IN()' or '=' sql fragment
+     * @param mixed $items A single value or array of values for the expression.
+     * @param int $type Parameter bounding type : SQL_PARAMS_QM or SQL_PARAMS_NAMED.
+     * @param string $prefix Named parameter placeholder prefix (a unique counter value is appended to each parameter name).
+     * @param bool $equal True means we want to equate to the constructed expression, false means we don't want to equate to it.
+     * @param mixed $onemptyitems This defines the behavior when the array of items provided is empty. Defaults to false,
      *              meaning throw exceptions. Other values will become part of the returned SQL fragment.
-     * @return array - $sql and $params
+     * @throws coding_exception | dml_exception
+     * @return array A list containing the constructed sql fragment and an array of parameters.
      */
     public function get_in_or_equal($items, $type=SQL_PARAMS_QM, $prefix='param', $equal=true, $onemptyitems=false) {
 
@@ -654,15 +672,19 @@ abstract class moodle_database {
     }
 
     /**
-     * Converts short table name {tablename} to real table name
-     * @param string sql
-     * @return string sql
+     * Converts short table name {tablename} to the real prefixed table name in given sql.
+     * @param string $sql The sql to be operated on.
+     * @return string The sql with tablenames being prefixed with $CFG->prefix
      */
     protected function fix_table_names($sql) {
         return preg_replace('/\{([a-z][a-z0-9_]*)\}/', $this->prefix.'$1', $sql);
     }
 
-    /** Internal function */
+    /**
+     * Internal private utitlity function used to fix parameters.
+     * Used with {@link preg_replace_callback()}
+     * @param array $match Refer to preg_replace_callback usage for description.
+     */
     private function _fix_sql_params_dollar_callback($match) {
         $this->fix_sql_params_i++;
         return "\$".$this->fix_sql_params_i;
@@ -670,8 +692,8 @@ abstract class moodle_database {
 
     /**
      * Normalizes sql query parameters and verifies parameters.
-     * @param string $sql query or part of it
-     * @param array $params query parameters
+     * @param string $sql The query or part of it.
+     * @param array $params The query parameters.
      * @return array (sql, params, type of params)
      */
     public function fix_sql_params($sql, array $params=null) {
@@ -822,27 +844,29 @@ abstract class moodle_database {
     }
 
     /**
-     * Return tables in database WITHOUT current prefix
+     * Return tables in database WITHOUT current prefix.
+     * @param bool $usecache if true, returns list of cached tables.
      * @return array of table names in lowercase and without prefix
      */
     public abstract function get_tables($usecache=true);
 
     /**
-     * Return table indexes - everything lowercased
-     * @return array of arrays
+     * Return table indexes - everything lowercased.
+     * @param string $table The table we want to get indexes from.
+     * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
      */
     public abstract function get_indexes($table);
 
     /**
      * Returns detailed information about columns in table. This information is cached internally.
-     * @param string $table name
-     * @param bool $usecache
+     * @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
      */
     public abstract function get_columns($table, $usecache=true);
 
     /**
-     * Normalise values based in RDBMS dependencies (booleans, LOBs...)
+     * Normalise values based on varying RDBMS's dependencies (booleans, LOBs...)
      *
      * @param database_column_info $column column metadata corresponding with the value we are going to normalise
      * @param mixed $value value we are going to normalise
@@ -851,8 +875,7 @@ abstract class moodle_database {
     protected abstract function normalise_value($column, $value);
 
     /**
-     * Reset internal column details cache
-     * @param string $table - empty means all, or one if name of table given
+     * Resets the internal column details cache
      * @return void
      */
     public function reset_caches() {
@@ -861,9 +884,10 @@ abstract class moodle_database {
     }
 
     /**
-     * Returns sql generator used for db manipulation.
+     * Returns the sql generator used for db manipulation.
      * Used mostly in upgrade.php scripts.
-     * @return database_manager instance
+     * @return database_manager The instance used to perform ddl operations.
+     * @see lib/ddl/database_manager.php
      */
     public function get_manager() {
         global $CFG;
@@ -881,15 +905,15 @@ abstract class moodle_database {
     }
 
     /**
-     * Attempt to change db encoding toUTF-8 if possible
-     * @return bool success
+     * Attempts to change db encoding to UTF-8 encoding if possible.
+     * @return bool True is successful.
      */
     public function change_db_encoding() {
         return false;
     }
 
     /**
-     * Is db in unicode mode?
+     * Checks to see if the database is in unicode mode?
      * @return bool
      */
     public function setup_is_unicodedb() {
@@ -897,7 +921,7 @@ abstract class moodle_database {
     }
 
     /**
-     * Enable/disable very detailed debugging
+     * Enable/disable very detailed debugging.
      * @param bool $state
      * @return void
      */
@@ -923,20 +947,20 @@ abstract class moodle_database {
     }
 
     /**
-     * Do NOT use in code, to be used by database_manager only!
+     * Do NOT use in code, this is for use by database_manager only!
      * @param string $sql query
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function change_database_structure($sql);
 
     /**
-     * Execute general sql query. Should be used only when no other method suitable.
+     * Executes a general sql query. Should be used only when no other method suitable.
      * Do NOT use this to make changes in db structure, use database_manager::execute_sql() instead!
      * @param string $sql query
      * @param array $params query parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function execute($sql, array $params=null);
 
@@ -969,10 +993,10 @@ abstract class moodle_database {
      * @param array $conditions optional array $fieldname=>requestedvalue with AND in between
      * @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
      * @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
-     * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @return moodle_recordset A moodle_recordset instance
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         list($select, $params) = $this->where_clause($table, $conditions);
@@ -985,17 +1009,17 @@ 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).
      * @param array $values array of values the field must have
      * @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
      * @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
-     * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @return moodle_recordset A moodle_recordset instance.
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset_list($table, $field, array $values, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         list($select, $params) = $this->where_clause_list($field, $values);
@@ -1012,17 +1036,17 @@ 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.
      * @param array $params array of sql parameters
      * @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
      * @param string $fields a comma separated list of fields to return (optional, by default all fields are returned).
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
-     * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @return moodle_recordset A moodle_recordset instance.
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         $sql = "SELECT $fields FROM {".$table."}";
@@ -1042,14 +1066,14 @@ 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
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
-     * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @return moodle_recordset A moodle_recordset instance.
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0);
 
@@ -1068,10 +1092,10 @@ abstract class moodle_database {
      * @param string $fields a comma separated list of fields to return (optional, by default
      *   all fields are returned). The first field will be used as key for the
      *   array so must be a unique field such as 'id'.
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
-     * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
-     * @return array of objects indexed by first column
-     * @throws dml_exception if error
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
+     * @param int $limitnum return a subset comprising this many records in total (optional, required if $limitfrom is set).
+     * @return array An array of Objects indexed by first column.
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         list($select, $params) = $this->where_clause($table, $conditions);
@@ -1081,17 +1105,17 @@ 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
-     * @param string $values array of values
+     * @param array $values An array of values
      * @param string $sort Sort order (as valid SQL sort parameter)
      * @param string $fields A comma separated list of fields to be returned from the chosen table. If specified,
      *   the first field should be a unique one such as 'id' since it will be used as a key in the associative
      *   array.
-     * @return array of objects indexed by first column
-     * @throws dml_exception if error
+     * @return array An array of objects indexed by first column
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_list($table, $field, array $values, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         list($select, $params) = $this->where_clause_list($field, $values);
@@ -1105,19 +1129,19 @@ 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 $table The table to query.
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
-     * @param array $params array of sql parameters
-     * @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
-     * @param string $fields a comma separated list of fields to return
+     * @param array $params An array of sql parameters
+     * @param string $sort An order to sort the results in (optional, a valid SQL ORDER BY parameter).
+     * @param string $fields A comma separated list of fields to return
      *   (optional, by default all fields are returned). The first field will be used as key for the
      *   array so must be a unique field such as 'id'.
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
-     * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
+     * @param int $limitnum return a subset comprising this many records in total (optional, required if $limitfrom is set).
      * @return array of objects indexed by first column
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         if ($select) {
@@ -1132,23 +1156,23 @@ 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
      *   returned array.
      * @param array $params array of sql parameters
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
-     * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
+     * @param int $limitnum return a subset comprising this many records in total (optional, required if $limitfrom is set).
      * @return array of objects indexed by first column
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=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,
@@ -1159,10 +1183,10 @@ abstract class moodle_database {
      * @param array $conditions optional array $fieldname=>requestedvalue with AND in between
      * @param string $sort an order to sort the results in (optional, a valid SQL ORDER BY parameter).
      * @param string $fields a comma separated list of fields to return - the number of fields should be 2!
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array an associative array
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_menu($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         $menu = array();
@@ -1180,18 +1204,18 @@ 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.
      * @param array $params array of sql parameters
      * @param string $sort Sort order (optional) - a valid SQL order parameter
      * @param string $fields A comma separated list of fields to be returned from the chosen table - the number of fields should be 2!
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array an associative array
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_select_menu($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0) {
         $menu = array();
@@ -1209,15 +1233,15 @@ 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
-     * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
+     * @param int $limitfrom return a subset of records, starting at this point (optional).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array an associative array
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_sql_menu($sql, array $params=null, $limitfrom=0, $limitnum=0) {
         $menu = array();
@@ -1240,9 +1264,11 @@ abstract class moodle_database {
      * @param string $fields A comma separated list of fields to be returned from the chosen table.
      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
      *                        IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
-     *                        MUST_EXIST means throw exception if no record or multiple records found
+     *                        MUST_EXIST means we will throw an exception if no record or multiple records found.
+     *
+     * @todo MDL-30407 MUST_EXIST option should not throw a dml_exception, it should throw a different exception as it's a requested check.
      * @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_record($table, array $conditions, $fields='*', $strictness=IGNORE_MISSING) {
         list($select, $params) = $this->where_clause($table, $conditions);
@@ -1259,7 +1285,7 @@ abstract class moodle_database {
      *                        IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
      *                        MUST_EXIST means throw exception if no record or multiple records found
      * @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_record_select($table, $select, array $params=null, $fields='*', $strictness=IGNORE_MISSING) {
         if ($select) {
@@ -1285,7 +1311,7 @@ abstract class moodle_database {
      *                        IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
      *                        MUST_EXIST means throw exception if no record or multiple records found
      * @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_record_sql($sql, array $params=null, $strictness=IGNORE_MISSING) {
         $strictness = (int)$strictness; // we support true/false for BC reasons too
@@ -1323,7 +1349,7 @@ abstract class moodle_database {
      *                        IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
      *                        MUST_EXIST means throw exception if no record or multiple records found
      * @return mixed the specified value false if not found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_field($table, $return, array $conditions, $strictness=IGNORE_MISSING) {
         list($select, $params) = $this->where_clause($table, $conditions);
@@ -1341,7 +1367,7 @@ abstract class moodle_database {
      *                        IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
      *                        MUST_EXIST means throw exception if no record or multiple records found
      * @return mixed the specified value false if not found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_field_select($table, $return, $select, array $params=null, $strictness=IGNORE_MISSING) {
         if ($select) {
@@ -1366,7 +1392,7 @@ abstract class moodle_database {
      *                        IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
      *                        MUST_EXIST means throw exception if no record or multiple records found
      * @return mixed the specified value false if not found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_field_sql($sql, array $params=null, $strictness=IGNORE_MISSING) {
         if (!$record = $this->get_record_sql($sql, $params, $strictness)) {
@@ -1385,7 +1411,7 @@ abstract class moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
      * @param array $params array of sql parameters
      * @return array of values
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_fieldset_select($table, $return, $select, array $params=null) {
         if ($select) {
@@ -1400,7 +1426,7 @@ abstract class moodle_database {
      * @param string $sql The SQL query
      * @param array $params array of sql parameters
      * @return array of values
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function get_fieldset_sql($sql, array $params=null);
 
@@ -1408,11 +1434,11 @@ abstract class moodle_database {
      * Insert new record into database, as fast as possible, no safety checks, lobs not supported.
      * @param string $table name
      * @param mixed $params data record as object or array
-     * @param bool $returnit return it of inserted record
+     * @param bool $returnid Returns id of inserted record.
      * @param bool $bulk true means repeated inserts expected
      * @param bool $customsequence true if 'id' included in $params, disables $returnid
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false);
 
@@ -1426,7 +1452,7 @@ abstract class moodle_database {
      * @param object $data A data object with values for one or more fields in the record
      * @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function insert_record($table, $dataobject, $returnid=true, $bulk=false);
 
@@ -1437,7 +1463,7 @@ abstract class moodle_database {
      * @param string $table name of database table to be inserted into
      * @param object $dataobject A data object with values for one or more fields in the record
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function import_record($table, $dataobject);
 
@@ -1445,9 +1471,9 @@ abstract class moodle_database {
      * Update record in database, as fast as possible, no safety checks, lobs not supported.
      * @param string $table name
      * @param mixed $params data record as object or array
-     * @param bool true means repeated updates expected
+     * @param bool $bulk True means repeated updates expected.
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function update_record_raw($table, $params, $bulk=false);
 
@@ -1460,9 +1486,9 @@ abstract class moodle_database {
      *
      * @param string $table The database table to be checked against.
      * @param object $dataobject An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
-     * @param bool true means repeated updates expected
+     * @param bool $bulk True means repeated updates expected.
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function update_record($table, $dataobject, $bulk=false);
 
@@ -1475,7 +1501,7 @@ abstract class moodle_database {
      * @param string $newvalue the value to set the field to.
      * @param array $conditions optional array $fieldname=>requestedvalue with AND in between
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function set_field($table, $newfield, $newvalue, array $conditions=null) {
         list($select, $params) = $this->where_clause($table, $conditions);
@@ -1491,7 +1517,7 @@ abstract class moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function set_field_select($table, $newfield, $newvalue, $select, array $params=null);
 
@@ -1502,7 +1528,7 @@ abstract class moodle_database {
      * @param string $table The table to query.
      * @param array $conditions optional array $fieldname=>requestedvalue with AND in between
      * @return int The count of records returned from the specified criteria.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function count_records($table, array $conditions=null) {
         list($select, $params) = $this->where_clause($table, $conditions);
@@ -1517,7 +1543,7 @@ abstract class moodle_database {
      * @param array $params array of sql parameters
      * @param string $countitem The count string to be used in the SQL call. Default is COUNT('x').
      * @return int The count of records returned from the specified criteria.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function count_records_select($table, $select, array $params=null, $countitem="COUNT('x')") {
         if ($select) {
@@ -1537,7 +1563,7 @@ abstract class moodle_database {
      * @param string $sql The SQL string you wish to be executed.
      * @param array $params array of sql parameters
      * @return int the count
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function count_records_sql($sql, array $params=null) {
         if ($count = $this->get_field_sql($sql, $params)) {
@@ -1556,7 +1582,7 @@ abstract class moodle_database {
      * @param string $table The table to check.
      * @param array $conditions optional array $fieldname=>requestedvalue with AND in between
      * @return bool true if a matching record exists, else false.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function record_exists($table, array $conditions) {
         list($select, $params) = $this->where_clause($table, $conditions);
@@ -1570,7 +1596,7 @@ abstract class moodle_database {
      * @param string $select A fragment of SQL to be used in a WHERE clause in the SQL call.
      * @param array $params array of sql parameters
      * @return bool true if a matching record exists, else false.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function record_exists_select($table, $select, array $params=null) {
         if ($select) {
@@ -1588,7 +1614,7 @@ abstract class moodle_database {
      * @param string $sql The SQL statement to execute.
      * @param array $params array of sql parameters
      * @return bool true if the SQL executes without errors and returns at least one record.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function record_exists_sql($sql, array $params=null) {
         $mrs = $this->get_recordset_sql($sql, $params, 0, 1);
@@ -1604,7 +1630,7 @@ abstract class moodle_database {
      * @param string $table the table to delete from.
      * @param array $conditions optional array $fieldname=>requestedvalue with AND in between
      * @return bool true.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function delete_records($table, array $conditions=null) {
         // truncate is drop/create (DDL), not transactional safe,
@@ -1623,7 +1649,7 @@ abstract class moodle_database {
      * @param string $field The field to search
      * @param array $values array of values
      * @return bool true.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function delete_records_list($table, $field, array $values) {
         list($select, $params) = $this->where_clause_list($field, $values);
@@ -1641,7 +1667,7 @@ abstract class moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
      * @param array $params array of sql parameters
      * @return bool true.
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public abstract function delete_records_select($table, $select, array $params=null);
 
@@ -1666,9 +1692,9 @@ abstract class moodle_database {
      * NOTE: The SQL result is a number and can not be used directly in
      *       SQL condition, please compare it to some number to get a bool!!
      *
-     * @param int $int1 first integer in the operation
-     * @param int $int2 second integer in the operation
-     * @return string the piece of SQL code to be used in your statement
+     * @param int $int1 First integer in the operation.
+     * @param int $int2 Second integer in the operation.
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_bitand($int1, $int2) {
         return '((' . $int1 . ') & (' . $int2 . '))';
@@ -1678,8 +1704,8 @@ abstract class moodle_database {
      * Returns the SQL text to be used in order to perform one bitwise NOT operation
      * with 1 integer.
      *
-     * @param int $int1 integer in the operation
-     * @return string the piece of SQL code to be used in your statement.
+     * @param int $int1 The operand integer in the operation.
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_bitnot($int1) {
         return '(~(' . $int1 . '))';
@@ -1692,9 +1718,9 @@ abstract class moodle_database {
      * NOTE: The SQL result is a number and can not be used directly in
      *       SQL condition, please compare it to some number to get a bool!!
      *
-     * @param int $int1 first integer in the operation
-     * @param int $int2 second integer in the operation
-     * @return string the piece of SQL code to be used in your statement.
+     * @param int $int1 The first operand integer in the operation.
+     * @param int $int2 The second operand integer in the operation.
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_bitor($int1, $int2) {
         return '((' . $int1 . ') | (' . $int2 . '))';
@@ -1707,9 +1733,9 @@ abstract class moodle_database {
      * NOTE: The SQL result is a number and can not be used directly in
      *       SQL condition, please compare it to some number to get a bool!!
      *
-     * @param int $int1 first integer in the operation
-     * @param int $int2 second integer in the operation
-     * @return string the piece of SQL code to be used in your statement.
+     * @param int $int1 The first operand integer in the operation.
+     * @param int $int2 The second operand integer in the operation.
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_bitxor($int1, $int2) {
         return '((' . $int1 . ') ^ (' . $int2 . '))';
@@ -1719,20 +1745,20 @@ abstract class moodle_database {
      * Returns the SQL text to be used in order to perform module '%'
      * operation - remainder after division
      *
-     * @param int $int1 first integer in the operation
-     * @param int $int2 second integer in the operation
-     * @return string the piece of SQL code to be used in your statement.
+     * @param int $int1 The first operand integer in the operation.
+     * @param int $int2 The second operand integer in the operation.
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_modulo($int1, $int2) {
         return '((' . $int1 . ') % (' . $int2 . '))';
     }
 
     /**
-     * Returns the correct CEIL expression applied to fieldname.
+     * Returns the cross db correct CEIL (ceiling) expression applied to fieldname.
+     * note: Most DBs use CEIL(), hence it's the default here.
      *
-     * @param string $fieldname the field (or expression) we are going to ceil
-     * @return string the piece of SQL code to be used in your ceiling statement
-     * Most DB use CEIL(), hence it's the default.
+     * @param string $fieldname The field (or expression) we are going to ceil.
+     * @return string The piece of SQL code to be used in your ceiling statement.
      */
     public function sql_ceil($fieldname) {
         return ' CEIL(' . $fieldname . ')';
@@ -1744,9 +1770,9 @@ abstract class moodle_database {
      * Be aware that the CHAR column you're trying to cast contains really
      * int values or the RDBMS will throw an error!
      *
-     * @param string $fieldname the name of the field to be casted
-     * @param bool $text to specify if the original column is one TEXT (CLOB) column (true). Defaults to false.
-     * @return string the piece of SQL code to be used in your statement.
+     * @param string $fieldname The name of the field to be casted.
+     * @param bool $text Specifies if the original column is one TEXT (CLOB) column (true). Defaults to false.
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_cast_char2int($fieldname, $text=false) {
         return ' ' . $fieldname . ' ';
@@ -1758,9 +1784,9 @@ abstract class moodle_database {
      * Be aware that the CHAR column you're trying to cast contains really
      * numbers or the RDBMS will throw an error!
      *
-     * @param string $fieldname the name of the field to be casted
-     * @param bool $text to specify if the original column is one TEXT (CLOB) column (true). Defaults to false.
-     * @return string the piece of SQL code to be used in your statement.
+     * @param string $fieldname The name of the field to be casted.
+     * @param bool $text Specifies if the original column is one TEXT (CLOB) column (true). Defaults to false.
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_cast_char2real($fieldname, $text=false) {
         return ' ' . $fieldname . ' ';
@@ -1772,8 +1798,8 @@ abstract class moodle_database {
      * (Only MySQL needs this. MySQL things that 1 * -1 = 18446744073709551615
      * if the 1 comes from an unsigned column).
      *
-     * @param string $fieldname the name of the field to be cast
-     * @return string the piece of SQL code to be used in your statement.
+     * @param string $fieldname The name of the field to be cast
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_cast_2signed($fieldname) {
         return ' ' . $fieldname . ' ';
@@ -1784,9 +1810,9 @@ abstract class moodle_database {
      * one varchar column, because some RDBMS doesn't support such direct
      * comparisons.
      *
-     * @param string $fieldname the name of the TEXT field we need to order by
-     * @param int $numchars of chars to use for the ordering (defaults to 32)
-     * @return string the piece of SQL code to be used in your statement.
+     * @param string $fieldname The name of the TEXT field we need to order by
+     * @param int $numchars Number of chars to use for the ordering (defaults to 32).
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_compare_text($fieldname, $numchars=32) {
         return $this->sql_order_by_text($fieldname, $numchars);
@@ -1795,13 +1821,13 @@ abstract class moodle_database {
     /**
      * Returns 'LIKE' part of a query.
      *
-     * @param string $fieldname usually name of the table column
-     * @param string $param usually bound query parameter (?, :named)
-     * @param bool $casesensitive use case sensitive search
-     * @param bool $accensensitive use accent sensitive search (not all databases support accent insensitive)
-     * @param bool $notlike true means "NOT LIKE"
-     * @param string $escapechar escape char for '%' and '_'
-     * @return string SQL code fragment
+     * @param string $fieldname Usually the name of the table column.
+     * @param string $param Usually the bound query parameter (?, :named).
+     * @param bool $casesensitive Use case sensitive search when set to true (default).
+     * @param bool $accentsensitive Use accent sensitive search when set to true (default). (not all databases support accent insensitive)
+     * @param bool $notlike True means "NOT LIKE".
+     * @param string $escapechar The escape char for '%' and '_'.
+     * @return string The SQL code fragment.
      */
     public function sql_like($fieldname, $param, $casesensitive = true, $accentsensitive = true, $notlike = false, $escapechar = '\\') {
         if (strpos($param, '%') !== false) {
@@ -1813,10 +1839,10 @@ abstract class moodle_database {
     }
 
     /**
-     * Escape sql LIKE special characters.
-     * @param string $text
-     * @param string $escapechar
-     * @return string
+     * Escape sql LIKE special characters like '_' or '%'.
+     * @param string $text The string containing characters needing escaping.
+     * @param string $escapechar The desired escape character, defaults to '\\'.
+     * @return string The escaped sql LIKE string.
      */
     public function sql_like_escape($text, $escapechar = '\\') {
         $text = str_replace('_', $escapechar.'_', $text);
@@ -1831,8 +1857,10 @@ abstract class moodle_database {
      * the case insensitive search using regexp_like() or NLS_COMP=LINGUISTIC :-(
      * See http://docs.moodle.org/en/XMLDB_Problems#Case-insensitive_searches
      *
-     * @deprecated
-     * @return string
+     * @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()
      */
     public function sql_ilike() {
         debugging('sql_ilike() is deprecated, please use sql_like() instead');
@@ -1840,12 +1868,13 @@ abstract class moodle_database {
     }
 
     /**
-     * Returns the proper SQL to do CONCAT between the elements passed
-     * Can take many parameters
+     * Returns the proper SQL to do CONCAT between the elements(fieldnames) passed.
      *
      * This function accepts variable number of string parameters.
+     * All strings/fieldnames will used in the SQL concatenate statement generated.
      *
-     * @return string
+     * @return string The SQL to concatenate strings passed in.
+     * @uses func_get_args()  and thus parameters are unlimited OPTIONAL number of additional field names.
      */
     public abstract function sql_concat();
 
@@ -1853,20 +1882,20 @@ abstract class moodle_database {
      * Returns the proper SQL to do CONCAT between the elements passed
      * with a given separator
      *
-     * @param string $separator
-     * @param array  $elements
-     * @return string
+     * @param string $separator The separator desired for the SQL concatenating $elements.
+     * @param array  $elements The array of strings to be concatenated.
+     * @return string The SQL to concatenate the strings.
      */
     public abstract function sql_concat_join($separator="' '", $elements=array());
 
     /**
      * Returns the proper SQL (for the dbms in use) to concatenate $firstname and $lastname
-     * TODO: Does this really need to be here? Eloy 20070727.
-     * TODO: we definitely do not! (skodak)
      *
-     * @param string $first User's first name
-     * @param string $last User's last name
-     * @return string
+     * @todo MDL-31233 This may not be needed here.
+     *
+     * @param string $first User's first name (default:'firstname').
+     * @param string $last User's last name (default:'lastname').
+     * @return string The SQL to concatenate strings.
      */
     function sql_fullname($first='firstname', $last='lastname') {
         return $this->sql_concat($first, "' '", $last);
@@ -1879,9 +1908,9 @@ abstract class moodle_database {
      * Note that the use or queries being ordered by TEXT columns must be minimised,
      * because it's really slooooooow.
      *
-     * @param string $fieldname the name of the TEXT field we need to order by
-     * @param string $numchars of chars to use for the ordering (defaults to 32)
-     * @return string the piece of SQL code to be used in your statement.
+     * @param string $fieldname The name of the TEXT field we need to order by.
+     * @param string $numchars The number of chars to use for the ordering (defaults to 32).
+     * @return string The piece of SQL code to be used in your statement.
      */
     public function sql_order_by_text($fieldname, $numchars=32) {
         return $fieldname;
@@ -1889,7 +1918,7 @@ abstract class moodle_database {
 
     /**
      * Returns the SQL text to be used to calculate the length in characters of one expression.
-     * @param string $fieldname or expression to calculate its length in characters.
+     * @param string $fieldname The fieldname/expression to calculate its length in characters.
      * @return string the piece of SQL code to be used in the statement.
      */
     public function sql_length($fieldname) {
@@ -1900,10 +1929,10 @@ abstract class moodle_database {
      * Returns the proper substr() SQL text used to extract substrings from DB
      * NOTE: this was originally returning only function name
      *
-     * @param string $expr some string field, no aggregates
-     * @param mixed $start integer or expression evaluating to int (1 based value; first char has index 1)
-     * @param mixed $length optional integer or expression evaluating to int
-     * @return string sql fragment
+     * @param string $expr Some string field, no aggregates.
+     * @param mixed $start Integer or expression evaluating to integer (1 based value; first char has index 1)
+     * @param mixed $length Optional integer or expression evaluating to integer.
+     * @return string The sql substring extraction fragment.
      */
     public function sql_substr($expr, $start, $length=false) {
         if (count(func_get_args()) < 2) {
@@ -1918,12 +1947,14 @@ abstract class moodle_database {
 
     /**
      * Returns the SQL for returning searching one string for the location of another.
+     *
      * Note, there is no guarantee which order $needle, $haystack will be in
-     * the resulting SQL, so when using this method, and both arguments contain
+     * the resulting SQL so when using this method, and both arguments contain
      * placeholders, you should use named placeholders.
+     *
      * @param string $needle the SQL expression that will be searched for.
      * @param string $haystack the SQL expression that will be searched in.
-     * @return string the required SQL
+     * @return string The required searching SQL part.
      */
     public function sql_position($needle, $haystack) {
         // Implementation using standard SQL.
@@ -1934,7 +1965,7 @@ abstract class moodle_database {
      * Returns the empty string char used by every supported DB. To be used when
      * we are searching for that values in our queries. Only Oracle uses this
      * for now (will be out, once we migrate to proper NULLs if that days arrives)
-     * @return string
+     * @return string An empty string.
      */
     function sql_empty() {
         return '';
@@ -1961,12 +1992,12 @@ abstract class moodle_database {
      *
      * (see parameters description below)
      *
-     * @param string $tablename name of the table (without prefix). Not used for now but can be
+     * @param string $tablename Name of the table (without prefix). Not used for now but can be
      *                          necessary in the future if we want to use some introspection using
      *                          meta information against the DB. /// TODO ///
-     * @param string $fieldname name of the field we are going to check
-     * @param boolean $nullablefield to specify if the field us nullable (true) or no (false) in the DB
-     * @param boolean $textfield to specify if it is a text (also called clob) field (true) or a varchar one (false)
+     * @param string $fieldname Name of the field we are going to check
+     * @param bool $nullablefield For specifying if the field is nullable (true) or no (false) in the DB.
+     * @param bool $textfield For specifying if it is a text (also called clob) field (true) or a varchar one (false)
      * @return string the sql code to be added to check for empty values
      */
     public function sql_isempty($tablename, $fieldname, $nullablefield, $textfield) {
@@ -1991,28 +2022,29 @@ abstract class moodle_database {
      *
      * (see parameters description below)
      *
-     * @param string $tablename name of the table (without prefix). Not used for now but can be
+     * @param string $tablename Name of the table (without prefix). This is not used for now but can be
      *                          necessary in the future if we want to use some introspection using
-     *                          meta information against the DB. /// TODO ///
-     * @param string $fieldname name of the field we are going to check
-     * @param boolean $nullablefield to specify if the field us nullable (true) or no (false) in the DB
-     * @param boolean $textfield to specify if it is a text (also called clob) field (true) or a varchar one (false)
-     * @return string the sql code to be added to check for non empty values
+     *                          meta information against the DB.
+     * @param string $fieldname The name of the field we are going to check.
+     * @param bool $nullablefield Specifies if the field is nullable (true) or not (false) in the DB.
+     * @param bool $textfield Specifies if it is a text (also called clob) field (true) or a varchar one (false).
+     * @return string The sql code to be added to check for non empty values.
      */
     public function sql_isnotempty($tablename, $fieldname, $nullablefield, $textfield) {
         return ' ( NOT ' . $this->sql_isempty($tablename, $fieldname, $nullablefield, $textfield) . ') ';
     }
 
     /**
-     * Does this driver suppoer regex syntax when searching
-     * @return bool
+     * Returns true if this database driver supports regex syntax when searching.
+     * @return bool True if supported.
      */
     public function sql_regex_supported() {
         return false;
     }
 
     /**
-     * Return regex positive or negative match sql
+     * Returns the driver specific syntax (SQL part) for matching regex positively or negatively (inverted matching).
+     * Eg: 'REGEXP':'NOT REGEXP' or '~*' : '!~*'
      * @param bool $positivematch
      * @return string or empty if not supported
      */
@@ -2023,7 +2055,8 @@ abstract class moodle_database {
 /// transactions
 
     /**
-     * Are transactions supported?
+     * Checks and returns true if transactions are supported.
+     *
      * It is not responsible to run productions servers
      * on databases without transaction support ;-)
      *
@@ -2037,7 +2070,7 @@ abstract class moodle_database {
     }
 
     /**
-     * Returns true if transaction in progress
+     * Returns true if a transaction is in progress.
      * @return bool
      */
     public function is_transaction_started() {
@@ -2045,7 +2078,7 @@ abstract class moodle_database {
     }
 
     /**
-     * Throws exception if transaction in progress.
+     * This is a test that throws an exception if transaction in progress.
      * This test does not force rollback of active transactions.
      * @return void
      */
@@ -2093,6 +2126,7 @@ abstract class moodle_database {
      * The real database transaction is committed only if
      * all delegated transactions committed.
      * @return void
+     * @throws dml_transaction_exception Creates and throws transaction related exceptions.
      */
     public function commit_delegated_transaction(moodle_transaction $transaction) {
         if ($transaction->is_disposed()) {
@@ -2137,9 +2171,9 @@ abstract class moodle_database {
      * because all open delegated transactions are rolled back
      * automatically if exceptions not caught.
      *
-     * @param moodle_transaction $transaction
-     * @param Exception $e exception that caused the problem
-     * @return void - does not return, exception is rethrown
+     * @param moodle_transaction $transaction An instance of a moodle_transaction.
+     * @param Exception $e The related exception to this transaction rollback.
+     * @return void This does not return, instead the exception passed in will be rethrown.
      */
     public function rollback_delegated_transaction(moodle_transaction $transaction, Exception $e) {
         if ($transaction->is_disposed()) {
@@ -2178,7 +2212,7 @@ abstract class moodle_database {
 
     /**
      * Force rollback of all delegated transaction.
-     * Does not trow any exceptions and does not log anything.
+     * Does not throw any exceptions and does not log anything.
      *
      * This method should be used only from default exception handlers and other
      * core code.
@@ -2209,43 +2243,45 @@ abstract class moodle_database {
     }
 
     /**
-     * Obtain session lock
-     * @param int $rowid id of the row with session record
-     * @param int $timeout max allowed time to wait for the lock in seconds
-     * @return bool success
+     * Obtains the session lock.
+     * @param int $rowid The id of the row with session record.
+     * @param int $timeout The maximum allowed time to wait for the lock in seconds.
+     * @return void
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_session_lock($rowid, $timeout) {
         $this->used_for_db_sessions = true;
     }
 
     /**
-     * Release session lock
-     * @param int $rowid id of the row with session record
-     * @return bool success
+     * Releases the session lock.
+     * @param int $rowid The id of the row with session record.
+     * @return void
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function release_session_lock($rowid) {
     }
 
 /// performance and logging
     /**
-     * Returns number of reads done by this database
-     * @return int
+     * Returns the number of reads done by this database.
+     * @return int Number of reads.
      */
     public function perf_get_reads() {
         return $this->reads;
     }
 
     /**
-     * Returns number of writes done by this database
-     * @return int
+     * Returns the number of writes done by this database.
+     * @return int Number of writes.
      */
     public function perf_get_writes() {
         return $this->writes;
     }
 
     /**
-     * Returns number of queries done by this database
-     * @return int
+     * Returns the number of queries done by this database.
+     * @return int Number of queries.
      */
     public function perf_get_queries() {
         return $this->writes + $this->reads;
index 120dc35..d1e7005 100644 (file)
@@ -20,6 +20,7 @@
  * Abstract recordset.
  *
  * @package    core
+ * @category   dml
  * @subpackage dml
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index f425164..505292c 100644 (file)
@@ -36,6 +36,7 @@
  * databases like postgres need this, because they don't lack any temp functionality.
  *
  * @package    core
+ * @category   dml
  * @subpackage dml
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -45,13 +46,16 @@ defined('MOODLE_INTERNAL') || die();
 
 class moodle_temptables {
 
-    protected $mdb;        // circular reference, to be able to use DB facilities here if needed
-    protected $prefix;     // prefix to be used for all the DB objects
-    protected $temptables; // simple array of moodle, not prefixed 'tablename' => DB, final (prefixed) 'tablename'
+    /** @var circular reference, to be able to use DB facilities here if needed */
+    protected $mdb;
+    /** @var prefix to be used for all the DB objects */
+    protected $prefix;
+    /** @var simple array of moodle, not prefixed 'tablename' => DB, final (prefixed) 'tablename' */
+    protected $temptables;
 
     /**
      * Creates new moodle_temptables instance
-     * @param object moodle_database instance
+     * @param moodle_database $mdb An instance of moodle_database.
      */
     public function __construct($mdb) {
         $this->mdb        = $mdb;
index 33bfadb..7709df2 100644 (file)
@@ -20,6 +20,7 @@
  * Delegated database transaction support.
  *
  * @package    core
+ * @category   dml
  * @subpackage dml
  * @copyright  2009 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -29,9 +30,17 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * Delegated transaction class.
+ *
+ * @package    core
+ * @category   dml
+ * @subpackage dml
+ * @copyright  2009 Petr Skoda (http://skodak.org)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class moodle_transaction {
+    /** @var array The debug_backtrace() returned array.*/
     private $start_backtrace;
+    /**@var moodle_database The moodle_database instance.*/
     private $database = null;
 
     /**
@@ -66,7 +75,7 @@ class moodle_transaction {
      * Mark transaction as disposed, no more
      * commits and rollbacks allowed.
      * To be used only from moodle_database class
-     * @return unknown_type
+     * @return null
      */
     public function dispose() {
         return $this->database = null;
index f1d3226..59e6918 100644 (file)
@@ -20,7 +20,7 @@
  * Native mssql class representing moodle database interface.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -33,6 +33,11 @@ require_once($CFG->libdir.'/dml/mssql_native_moodle_temptables.php');
 
 /**
  * Native mssql class representing moodle database interface.
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class mssql_native_moodle_database extends moodle_database {
 
@@ -115,10 +120,10 @@ class mssql_native_moodle_database extends moodle_database {
     /**
      * Connect to db
      * Must be called before other methods.
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database username.
+     * @param string $dbpass The database username's password.
+     * @param string $dbname The name of the database being connected to.
      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return bool true
@@ -257,7 +262,7 @@ class mssql_native_moodle_database extends moodle_database {
 
     /**
      * Returns database server info array
-     * @return array
+     * @return array Array containing 'description' and 'version' info
      */
     public function get_server_info() {
         static $info;
@@ -311,7 +316,7 @@ class mssql_native_moodle_database extends moodle_database {
 
     /**
      * Returns supported query parameter types
-     * @return int bitmask
+     * @return int bitmask of accepted SQL_PARAMS_*
      */
     protected function allowed_param_types() {
         return SQL_PARAMS_QM; // Not really, but emulated, see emulate_bound_params()
@@ -327,6 +332,7 @@ class mssql_native_moodle_database extends moodle_database {
 
     /**
      * Return tables in database WITHOUT current prefix
+     * @param bool $usecache if true, returns list of cached tables.
      * @return array of table names in lowercase and without prefix
      */
     public function get_tables($usecache=true) {
@@ -360,8 +366,9 @@ class mssql_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Return table indexes - everything lowercased
-     * @return array of arrays
+     * Return table indexes - everything lowercased.
+     * @param string $table The table we want to get indexes from.
+     * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
      */
     public function get_indexes($table) {
         $indexes = array();
@@ -503,7 +510,7 @@ class mssql_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Normalise values based in RDBMS dependencies (booleans, LOBs...)
+     * Normalise values based on varying RDBMS's dependencies (booleans, LOBs...)
      *
      * @param database_column_info $column column metadata corresponding with the value we are going to normalise
      * @param mixed $value value we are going to normalise
@@ -594,7 +601,7 @@ class mssql_native_moodle_database extends moodle_database {
      * Do NOT use in code, to be used by database_manager only!
      * @param string $sql query
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function change_database_structure($sql) {
         $this->reset_caches();
@@ -652,7 +659,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param string $sql query
      * @param array $params query parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function execute($sql, array $params=null) {
 
@@ -678,14 +685,15 @@ 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
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
         $limitfrom = (int)$limitfrom;
@@ -724,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
@@ -733,7 +742,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array of objects, or empty array if no records were found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
 
@@ -760,7 +769,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param string $sql The SQL query
      * @param array $params array of sql parameters
      * @return array of values
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_fieldset_sql($sql, array $params=null) {
 
@@ -784,7 +793,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param bool $bulk true means repeated inserts expected
      * @param bool $customsequence true if 'id' included in $params, disables $returnid
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
         if (!is_array($params)) {
@@ -864,7 +873,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param object $data A data object with values for one or more fields in the record
      * @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -893,7 +902,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param string $table name of database table to be inserted into
      * @param object $dataobject A data object with values for one or more fields in the record
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function import_record($table, $dataobject) {
         $dataobject = (array)$dataobject;
@@ -920,7 +929,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param mixed $params data record as object or array
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record_raw($table, $params, $bulk=false) {
         $params = (array)$params;
@@ -967,7 +976,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param object $dataobject An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record($table, $dataobject, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -995,7 +1004,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
 
@@ -1042,7 +1051,7 @@ class mssql_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function delete_records_select($table, $select, array $params=null) {
 
index d5f3481..d383d31 100644 (file)
@@ -19,7 +19,7 @@
  * MSSQL specific recordset.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index b598503..9242059 100644 (file)
@@ -21,7 +21,7 @@
  * temp table names included in the get_tables() method of the DB.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index fabfb3f..3f70bef 100644 (file)
@@ -20,7 +20,7 @@
  * Native mysqli class representing moodle database interface.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -33,6 +33,11 @@ require_once($CFG->libdir.'/dml/mysqli_native_moodle_temptables.php');
 
 /**
  * Native mysqli class representing moodle database interface.
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Petr Skoda (http://skodak.org)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class mysqli_native_moodle_database extends moodle_database {
 
@@ -47,7 +52,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param string $dbpass
      * @param string $dbname
      * @return bool success
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function create_database($dbhost, $dbuser, $dbpass, $dbname, array $dboptions=null) {
         $driverstatus = $this->driver_installed();
@@ -258,10 +263,10 @@ class mysqli_native_moodle_database extends moodle_database {
     /**
      * Connect to db
      * Must be called before other methods.
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database username.
+     * @param string $dbpass The database username's password.
+     * @param string $dbname The name of the database being connected to.e
      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return bool success
@@ -340,7 +345,7 @@ class mysqli_native_moodle_database extends moodle_database {
 
     /**
      * Returns database server info array
-     * @return array
+     * @return array Array containing 'description' and 'version' info
      */
     public function get_server_info() {
         return array('description'=>$this->mysqli->server_info, 'version'=>$this->mysqli->server_info);
@@ -348,7 +353,7 @@ class mysqli_native_moodle_database extends moodle_database {
 
     /**
      * Returns supported query parameter types
-     * @return int bitmask
+     * @return int bitmask of accepted SQL_PARAMS_*
      */
     protected function allowed_param_types() {
         return SQL_PARAMS_QM;
@@ -364,6 +369,7 @@ class mysqli_native_moodle_database extends moodle_database {
 
     /**
      * Return tables in database WITHOUT current prefix
+     * @param bool $usecache if true, returns list of cached tables.
      * @return array of table names in lowercase and without prefix
      */
     public function get_tables($usecache=true) {
@@ -395,8 +401,9 @@ class mysqli_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Return table indexes - everything lowercased
-     * @return array of arrays
+     * Return table indexes - everything lowercased.
+     * @param string $table The table we want to get indexes from.
+     * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
      */
     public function get_indexes($table) {
         $indexes = array();
@@ -659,7 +666,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * Do NOT use in code, to be used by database_manager only!
      * @param string $sql query
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function change_database_structure($sql) {
         $this->reset_caches();
@@ -706,7 +713,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param string $sql query
      * @param array $params query parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function execute($sql, array $params=null) {
         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
@@ -737,14 +744,15 @@ 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
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
         $limitfrom = (int)$limitfrom;
@@ -777,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
@@ -786,7 +795,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array of objects, or empty array if no records were found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
         $limitfrom = (int)$limitfrom;
@@ -830,7 +839,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param string $sql The SQL query
      * @param array $params array of sql parameters
      * @return array of values
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_fieldset_sql($sql, array $params=null) {
         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
@@ -858,7 +867,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param bool $bulk true means repeated inserts expected
      * @param bool $customsequence true if 'id' included in $params, disables $returnid
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
         if (!is_array($params)) {
@@ -913,7 +922,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param object $data A data object with values for one or more fields in the record
      * @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -942,7 +951,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param string $table name of database table to be inserted into
      * @param object $dataobject A data object with values for one or more fields in the record
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function import_record($table, $dataobject) {
         $dataobject = (array)$dataobject;
@@ -966,7 +975,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param mixed $params data record as object or array
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record_raw($table, $params, $bulk=false) {
         $params = (array)$params;
@@ -1012,7 +1021,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param object $dataobject An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record($table, $dataobject, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -1040,7 +1049,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
         if ($select) {
@@ -1080,7 +1089,7 @@ class mysqli_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function delete_records_select($table, $select, array $params=null) {
         if ($select) {
index fae0043..e8dc5bc 100644 (file)
@@ -20,7 +20,7 @@
  * Mysqli specific recordset.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -31,6 +31,11 @@ require_once($CFG->libdir.'/dml/moodle_recordset.php');
 
 /**
  * Mysqli specific moodle recordset class
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Petr Skoda (http://skodak.org)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class mysqli_native_moodle_recordset extends moodle_recordset {
 
index 595082e..0ad5132 100644 (file)
@@ -21,7 +21,7 @@
  * temp table names included in the get_tables() method of the DB.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 40b046c..bc08fb9 100644 (file)
@@ -20,7 +20,7 @@
  * Native oci class representing moodle database interface.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -36,19 +36,29 @@ require_once($CFG->libdir.'/dml/oci_native_moodle_temptables.php');
  *
  * One complete reference for PHP + OCI:
  * http://www.oracle.com/technology/tech/php/underground-php-oracle-manual.html
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Petr Skoda (http://skodak.org)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class oci_native_moodle_database extends moodle_database {
 
     protected $oci     = null;
 
-    private $last_stmt_error = null; // To store stmt errors and enable get_last_error() to detect them
-    private $commit_status = null;   // default value initialised in connect method, we need the driver to be present
+    /** @var To store stmt errors and enable get_last_error() to detect them.*/
+    private $last_stmt_error = null;
+    /** @var Default value initialised in connect method, we need the driver to be present.*/
+    private $commit_status = null;
 
-    private $last_error_reporting; // To handle oci driver default verbosity
-    private $unique_session_id; // To store unique_session_id. Needed for temp tables unique naming
-
-    private $dblocks_supported = null; // To cache locks support along the connection life
-    private $bitwise_supported = null; // To cache bitwise operations support along the connection life
+    /** @var To handle oci driver default verbosity.*/
+    private $last_error_reporting;
+    /** @var To store unique_session_id. Needed for temp tables unique naming.*/
+    private $unique_session_id;
+    /** @var To cache locks support along the connection life.*/
+    private $dblocks_supported = null;
+    /** @var To cache bitwise operations support along the connection life.*/
+    private $bitwise_supported = null;
 
     /**
      * Detects if all needed PHP stuff installed.
@@ -132,10 +142,10 @@ class oci_native_moodle_database extends moodle_database {
     /**
      * Connect to db
      * Must be called before other methods.
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database username.
+     * @param string $dbpass The database username's password.
+     * @param string $dbname The name of the database being connected to.
      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return bool true
@@ -270,7 +280,7 @@ class oci_native_moodle_database extends moodle_database {
 
     /**
      * Returns database server info array
-     * @return array
+     * @return array Array containing 'description' and 'version' info
      */
     public function get_server_info() {
         static $info = null; // TODO: move to real object property
@@ -315,7 +325,7 @@ class oci_native_moodle_database extends moodle_database {
 
     /**
      * Returns supported query parameter types
-     * @return int bitmask
+     * @return int bitmask of accepted SQL_PARAMS_*
      */
     protected function allowed_param_types() {
         return SQL_PARAMS_NAMED;
@@ -386,6 +396,7 @@ class oci_native_moodle_database extends moodle_database {
 
     /**
      * Return tables in database WITHOUT current prefix
+     * @param bool $usecache if true, returns list of cached tables.
      * @return array of table names in lowercase and without prefix
      */
     public function get_tables($usecache=true) {
@@ -422,8 +433,9 @@ class oci_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Return table indexes - everything lowercased
-     * @return array of arrays
+     * Return table indexes - everything lowercased.
+     * @param string $table The table we want to get indexes from.
+     * @return array An associative array of indexes containing 'unique' flag and 'columns' being indexed
      */
     public function get_indexes($table) {
         $indexes = array();
@@ -870,7 +882,7 @@ class oci_native_moodle_database extends moodle_database {
      * Do NOT use in code, to be used by database_manager only!
      * @param string $sql query
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function change_database_structure($sql) {
         $this->reset_caches();
@@ -982,7 +994,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param string $sql query
      * @param array $params query parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function execute($sql, array $params=null) {
         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
@@ -1014,7 +1026,7 @@ class oci_native_moodle_database extends moodle_database {
      *                        IGNORE_MULTIPLE means return first, ignore multiple records found(not recommended);
      *                        MUST_EXIST means throw exception if no record or multiple records found
      * @return mixed a fieldset object containing the first matching record, false or exception if error not found depending on mode
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_record_sql($sql, array $params=null, $strictness=IGNORE_MISSING) {
         $strictness = (int)$strictness;
@@ -1039,14 +1051,15 @@ 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
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
 
@@ -1071,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
@@ -1080,7 +1094,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array of objects, or empty array if no records were found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
 
@@ -1122,7 +1136,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param string $sql The SQL query
      * @param array $params array of sql parameters
      * @return array of values
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_fieldset_sql($sql, array $params=null) {
         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
@@ -1152,7 +1166,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param bool $bulk true means repeated inserts expected
      * @param bool $customsequence true if 'id' included in $params, disables $returnid
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
         if (!is_array($params)) {
@@ -1224,7 +1238,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param object $data A data object with values for one or more fields in the record
      * @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -1253,7 +1267,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param string $table name of database table to be inserted into
      * @param object $dataobject A data object with values for one or more fields in the record
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function import_record($table, $dataobject) {
         $dataobject = (array)$dataobject;
@@ -1278,7 +1292,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param mixed $params data record as object or array
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record_raw($table, $params, $bulk=false) {
         $params = (array)$params;
@@ -1327,7 +1341,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param object $dataobject An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record($table, $dataobject, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -1357,7 +1371,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
 
@@ -1413,7 +1427,7 @@ class oci_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function delete_records_select($table, $select, array $params=null) {
 
@@ -1581,6 +1595,12 @@ class oci_native_moodle_database extends moodle_database {
         }
     }
 
+    /**
+     * Returns the empty string char used by every supported DB. To be used when
+     * we are searching for that values in our queries. Only Oracle uses this
+     * for now (will be out, once we migrate to proper NULLs if that days arrives)
+     * @return string A string with single whitespace.
+     */
     public function sql_empty() {
         return ' ';
     }
index 84eddd5..042c610 100644 (file)
@@ -15,7 +15,7 @@
 
 /**
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  * @version    20091010 (plz, keep this updated for easier reference)
index ed1112b..4d8694a 100644 (file)
@@ -20,7 +20,7 @@
  * Oracle specific recordset.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 3c2a657..1343d06 100644 (file)
@@ -23,7 +23,7 @@
  * method of the DB.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 2cc8770..5f54613 100644 (file)
@@ -20,7 +20,7 @@
  * Experimental pdo database class
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Andrei Bautu
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -32,6 +32,11 @@ require_once($CFG->libdir.'/dml/pdo_moodle_recordset.php');
 
 /**
  * Experimental pdo database class
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Andrei Bautu
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class pdo_moodle_database extends moodle_database {
 
@@ -50,10 +55,10 @@ abstract class pdo_moodle_database extends moodle_database {
     /**
      * Connect to db
      * Must be called before other methods.
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database username.
+     * @param string $dbpass The database username's password.
+     * @param string $dbname The name of the database being connected to.
      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return bool success
@@ -138,7 +143,7 @@ abstract class pdo_moodle_database extends moodle_database {
 
     /**
      * Returns database server info array
-     * @return array
+     * @return array Array containing 'description' and 'version' info
      */
     public function get_server_info() {
         $result = array();
@@ -153,7 +158,7 @@ abstract class pdo_moodle_database extends moodle_database {
 
     /**
      * Returns supported query parameter types
-     * @return int bitmask
+     * @return int bitmask of accepted SQL_PARAMS_*
      */
     protected function allowed_param_types() {
         return SQL_PARAMS_QM | SQL_PARAMS_NAMED;
@@ -250,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
@@ -303,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
index 64be1bd..803416f 100644 (file)
@@ -20,7 +20,7 @@
  * Experimental pdo recordset
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Andrei Bautu
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -31,6 +31,11 @@ require_once($CFG->libdir.'/dml/moodle_recordset.php');
 
 /**
  * Experimental pdo recordset
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Andrei Bautu
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class pdo_moodle_recordset extends moodle_recordset {
 
index 24f8fb0..cdd1c5e 100644 (file)
@@ -20,7 +20,7 @@
  * Native pgsql class representing moodle database interface.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -33,6 +33,11 @@ require_once($CFG->libdir.'/dml/pgsql_native_moodle_temptables.php');
 
 /**
  * Native pgsql class representing moodle database interface.
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Petr Skoda (http://skodak.org)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class pgsql_native_moodle_database extends moodle_database {
 
@@ -110,10 +115,10 @@ class pgsql_native_moodle_database extends moodle_database {
     /**
      * Connect to db
      * Must be called before other methods.
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database username.
+     * @param string $dbpass The database username's password.
+     * @param string $dbname The name of the database being connected to.
      * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return bool true
@@ -234,7 +239,7 @@ class pgsql_native_moodle_database extends moodle_database {
 
     /**
      * Returns database server info array
-     * @return array
+     * @return array Array containing 'description' and 'version' info
      */
     public function get_server_info() {
         static $info;
@@ -254,7 +259,7 @@ class pgsql_native_moodle_database extends moodle_database {
 
     /**
      * Returns supported query parameter types
-     * @return int bitmask
+     * @return int bitmask of accepted SQL_PARAMS_*
      */
     protected function allowed_param_types() {
         return SQL_PARAMS_DOLLAR;
@@ -269,7 +274,8 @@ class pgsql_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Return tables in database WITHOUT current prefix
+     * Return tables in database WITHOUT current prefix.
+     * @param bool $usecache if true, returns list of cached tables.
      * @return array of table names in lowercase and without prefix
      */
     public function get_tables($usecache=true) {
@@ -303,7 +309,8 @@ class pgsql_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Return table indexes - everything lowercased
+     * Return table indexes - everything lowercased.
+     * @param string $table The table we want to get indexes from.
      * @return array of arrays
      */
     public function get_indexes($table) {
@@ -563,7 +570,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * Do NOT use in code, to be used by database_manager only!
      * @param string $sql query
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function change_database_structure($sql) {
         $this->reset_caches();
@@ -582,7 +589,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param string $sql query
      * @param array $params query parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function execute($sql, array $params=null) {
         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
@@ -606,14 +613,15 @@ 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
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
         $limitfrom = (int)$limitfrom;
@@ -646,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
@@ -655,7 +664,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array of objects, or empty array if no records were found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0) {
         $limitfrom = (int)$limitfrom;
@@ -717,7 +726,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param string $sql The SQL query
      * @param array $params array of sql parameters
      * @return array of values
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_fieldset_sql($sql, array $params=null) {
         list($sql, $params, $type) = $this->fix_sql_params($sql, $params);
@@ -740,7 +749,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param bool $bulk true means repeated inserts expected
      * @param bool $customsequence true if 'id' included in $params, disables $returnid
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
         if (!is_array($params)) {
@@ -803,7 +812,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param object $data A data object with values for one or more fields in the record
      * @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record($table, $dataobject, $returnid=true, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -857,7 +866,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param string $table name of database table to be inserted into
      * @param object $dataobject A data object with values for one or more fields in the record
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function import_record($table, $dataobject) {
         $dataobject = (array)$dataobject;
@@ -904,7 +913,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param mixed $params data record as object or array
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record_raw($table, $params, $bulk=false) {
         $params = (array)$params;
@@ -950,7 +959,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param object $dataobject An object with contents equal to fieldname=>fieldvalue. Must have an entry for 'id' to map to the table specified.
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function update_record($table, $dataobject, $bulk=false) {
         $dataobject = (array)$dataobject;
@@ -1003,7 +1012,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call.
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function set_field_select($table, $newfield, $newvalue, $select, array $params=null) {
 
@@ -1056,7 +1065,7 @@ class pgsql_native_moodle_database extends moodle_database {
      * @param string $select A fragment of SQL to be used in a where clause in the SQL call (used to define the selection criteria).
      * @param array $params array of sql parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function delete_records_select($table, $select, array $params=null) {
         if ($select) {
index 70d655e..6d00d15 100644 (file)
@@ -20,7 +20,7 @@
  * Native postgresql recordset.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Petr Skoda (http://skodak.org)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -31,11 +31,17 @@ require_once($CFG->libdir.'/dml/moodle_recordset.php');
 
 /**
  * pgsql specific moodle recordset class
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Petr Skoda (http://skodak.org)
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class pgsql_native_moodle_recordset extends moodle_recordset {
 
     protected $result;
-    protected $current; // current row as array
+    /** @var current row as array.*/
+    protected $current;
     protected $bytea_oid;
     protected $blobs = array();
 
index c58bf4b..4227da1 100644 (file)
@@ -21,7 +21,7 @@
  * temp table names included in the get_tables() method of the DB.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2010 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 923cf60..b28334c 100644 (file)
@@ -20,7 +20,7 @@
  * Experimental pdo database class.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2008 Andrei Bautu
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -31,6 +31,11 @@ require_once($CFG->libdir.'/dml/pdo_moodle_database.php');
 
 /**
  * Experimental pdo database class
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2008 Andrei Bautu
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class sqlite3_pdo_moodle_database extends pdo_moodle_database {
     protected $database_file_extension = '.sq3.php';
@@ -132,7 +137,8 @@ class sqlite3_pdo_moodle_database extends pdo_moodle_database {
     }
 
     /**
-     * Return tables in database WITHOUT current prefix
+     * Return tables in database WITHOUT current prefix.
+     * @param bool $usecache if true, returns list of cached tables.
      * @return array of table names in lowercase and without prefix
      */
     public function get_tables($usecache=true) {
@@ -156,6 +162,7 @@ class sqlite3_pdo_moodle_database extends pdo_moodle_database {
 
     /**
      * Return table indexes - everything lowercased
+     * @param string $table The table we want to get indexes from.
      * @return array of arrays
      */
     public function get_indexes($table) {
index 6156759..a938679 100644 (file)
@@ -19,7 +19,7 @@
  * Native sqlsrv class representing moodle database interface.
  *
  * @package    core
- * @subpackage dml
+ * @subpackage dml_driver
  * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
  */
@@ -32,6 +32,11 @@ require_once($CFG->libdir.'/dml/sqlsrv_native_moodle_temptables.php');
 
 /**
  * Native sqlsrv class representing moodle database interface.
+ *
+ * @package    core
+ * @subpackage dml_driver
+ * @copyright  2009 onwards Eloy Lafuente (stronk7) {@link http://stronk7.com}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v2 or later
  */
 class sqlsrv_native_moodle_database extends moodle_database {
 
@@ -126,12 +131,12 @@ class sqlsrv_native_moodle_database extends moodle_database {
 
     /**
      * Connect to db
-     * Must be called before other methods.
-     * @param string $dbhost
-     * @param string $dbuser
-     * @param string $dbpass
-     * @param string $dbname
-     * @param mixed $prefix string means moodle db prefix, false used for external databases where prefix not used
+     * Must be called before most other methods. (you can call methods that return connection configuration parameters)
+     * @param string $dbhost The database host.
+     * @param string $dbuser The database username.
+     * @param string $dbpass The database username's password.
+     * @param string $dbname The name of the database being connected to.
+     * @param mixed $prefix string|bool The moodle db table name's prefix. false is used for external databases where prefix not used
      * @param array $dboptions driver specific options
      * @return bool true
      * @throws dml_connection_exception if error
@@ -234,7 +239,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
     /**
      * Called before each db query.
      * @param string $sql
-     * @param array array of parameters
+     * @param array $params array of parameters
      * @param int $type type of query
      * @param mixed $extrainfo driver specific extra information
      * @return void
@@ -254,7 +259,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
 
     /**
      * Returns database server info array
-     * @return array
+     * @return array Array containing 'description', 'version' and 'database' (current db) info
      */
     public function get_server_info() {
         static $info;
@@ -375,7 +380,8 @@ class sqlsrv_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Return tables in database WITHOUT current prefix
+     * Return tables in database WITHOUT current prefix.
+     * @param bool $usecache if true, returns list of cached tables.
      * @return array of table names in lowercase and without prefix
      */
     public function get_tables($usecache = true) {
@@ -410,7 +416,8 @@ class sqlsrv_native_moodle_database extends moodle_database {
     }
 
     /**
-     * Return table indexes - everything lowercased
+     * Return table indexes - everything lowercased.
+     * @param string $table The table we want to get indexes from.
      * @return array of arrays
      */
     public function get_indexes($table) {
@@ -665,7 +672,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * Do NOT use in code, to be used by database_manager only!
      * @param string $sql query
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function change_database_structure($sql) {
         $this->reset_caches();
@@ -728,7 +735,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * @param string $sql query
      * @param array $params query parameters
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function execute($sql, array $params = null) {
         if (strpos($sql, ';') !== false) {
@@ -745,14 +752,15 @@ 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
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return moodle_recordset instance
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_recordset_sql($sql, array $params = null, $limitfrom = 0, $limitnum = 0) {
         $limitfrom = (int)$limitfrom;
@@ -791,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
@@ -800,7 +809,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
      * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
      * @return array of objects, or empty array if no records were found
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_records_sql($sql, array $params = null, $limitfrom = 0, $limitnum = 0) {
 
@@ -828,7 +837,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * @param string $sql The SQL query
      * @param array $params array of sql parameters
      * @return array of values
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function get_fieldset_sql($sql, array $params = null) {
 
@@ -852,7 +861,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * @param bool $bulk true means repeated inserts expected
      * @param bool $customsequence true if 'id' included in $params, disables $returnid
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record_raw($table, $params, $returnid=true, $bulk=false, $customsequence=false) {
         if (!is_array($params)) {
@@ -937,7 +946,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * @param object $data A data object with values for one or more fields in the record
      * @param bool $returnid Should the id of the newly created record entry be returned? If this option is not requested then true/false is returned.
      * @return bool|int true or new id
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function insert_record($table, $dataobject, $returnid = true, $bulk = false) {
         $dataobject = (array)$dataobject;
@@ -966,7 +975,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * @param string $table name of database table to be inserted into
      * @param object $dataobject A data object with values for one or more fields in the record
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */
     public function import_record($table, $dataobject) {
         if (!is_object($dataobject)) {
@@ -995,7 +1004,7 @@ class sqlsrv_native_moodle_database extends moodle_database {
      * @param mixed $params data record as object or array
      * @param bool true means repeated updates expected
      * @return bool true
-     * @throws dml_exception if error
+     * @throws dml_exception A DML specific exception is thrown for any errors.
      */