From 3564771d6bcd37f44b4ff4b9f38027801000a4a8 Mon Sep 17 00:00:00 2001 From: samhemelryk Date: Fri, 22 May 2009 08:41:00 +0000 Subject: [PATCH] lib MDL-19236 added phpdocs and copyrights --- lib/completionlib.php | 2 +- lib/componentlib.class.php | 3 +- lib/conditionlib.php | 89 ++++++++-- lib/cssconstants.php | 148 +++++++++-------- lib/csvlib.class.php | 89 ++++++++-- lib/customcheckslib.php | 70 ++++---- lib/datalib.php | 325 ++++++++++++++++++++++++++++--------- lib/ddllib.php | 124 +++++++++----- 8 files changed, 596 insertions(+), 254 deletions(-) diff --git a/lib/completionlib.php b/lib/completionlib.php index c0d2a1ac68..c29059a6a7 100644 --- a/lib/completionlib.php +++ b/lib/completionlib.php @@ -22,7 +22,7 @@ * Completion top-level options (admin setting enablecompletion) * * @package moodlecore - * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/lib/componentlib.class.php b/lib/componentlib.class.php index beb2bf942d..71ccaf00c1 100644 --- a/lib/componentlib.class.php +++ b/lib/componentlib.class.php @@ -121,8 +121,7 @@ * That's all! * * @package moodlecore - * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com - * 2001 onwards Eloy Lafuente (stronk7) http://contiento.com + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/lib/conditionlib.php b/lib/conditionlib.php index 352b8540c4..b9f2e663aa 100644 --- a/lib/conditionlib.php +++ b/lib/conditionlib.php @@ -1,6 +1,27 @@ . + +/** + * Used for tracking conditions that apply before activities are displayed + * to students ('conditional availability'). + * + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ /** The activity is not displayed to students at all when conditions aren't met. */ define('CONDITION_STUDENTVIEW_HIDE',0); @@ -16,19 +37,34 @@ define('CONDITION_MISSING_EXTRATABLE',1); /** The $cm variable is expected to contain nothing except the ID */ define('CONDITION_MISSING_EVERYTHING',2); +/** + * @global stdClass $CONDITIONLIB_PRIVATE + * @name $CONDITIONLIB_PRIVATE + */ global $CONDITIONLIB_PRIVATE; $CONDITIONLIB_PRIVATE = new stdClass; // Caches whether completion values are used in availability conditions. // Array of course => array of cmid => true. $CONDITIONLIB_PRIVATE->usedincondition = array(); - +/** + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package moodlecore + */ class condition_info { + /** + * @var object, bool + */ private $cm, $gotdata; /** * Constructs with course-module details. * + * @global object + * @uses CONDITION_MISSING_NOTHING + * @uses CONDITION_MISSING_EVERYTHING + * @uses DEBUG_DEVELOPER + * @uses CONDITION_MISSING_EXTRATABLE * @param object $cm Moodle course-module object. May have extra fields * ->conditionsgrade, ->conditionscompletion which should come from * get_fast_modinfo. Should have ->availablefrom, ->availableuntil, @@ -92,7 +128,9 @@ class condition_info { * Adds the extra availability conditions (if any) into the given * course-module object. * - * @param object &$cm Moodle course-module data object + * @global object + * @global object + * @param object $cm Moodle course-module data object */ public static function fill_availability_conditions(&$cm) { if (empty($cm->id)) { @@ -132,6 +170,8 @@ WHERE /** * Obtains the name of a grade item. + * + * @global object * @param object $gradeitemobj Object from get_record on grade_items table, * (can be empty if you want to just get !missing) * @return string Name of item of !missing if it didn't exist @@ -149,9 +189,9 @@ WHERE } /** - * @return A course-module object with all the information required to + * @see require_data() + * @return object A course-module object with all the information required to * determine availability. - * @throws coding_exception If data wasn't loaded */ public function get_full_course_module() { $this->require_data(); @@ -160,6 +200,8 @@ WHERE /** * Adds to the database a condition based on completion of another module. + * + * @global object * @param int $cmid ID of other module * @param int $requiredcompletion COMPLETION_xx constant */ @@ -177,6 +219,8 @@ WHERE /** * Adds to the database a condition based on the value of a grade item. + * + * @global object * @param int $gradeitemid ID of grade item * @param float $min Minimum grade (>=), up to 5 decimal points, or null if none * @param float $max Maximum grade (<), up to 5 decimal points, or null if none @@ -211,6 +255,8 @@ WHERE /** * Erases from the database all conditions for this activity. + * + * @global object */ public function wipe_conditions() { // Wipe from DB @@ -226,12 +272,14 @@ WHERE /** * Obtains a string describing all availability restrictions (even if * they do not apply any more). + * + * @global object + * @global object * @param object $modinfo Usually leave as null for default. Specify when * calling recursively from inside get_fast_modinfo. The value supplied * here must include list of all CMs with 'id' and 'name' * @return string Information string (for admin) about all restrictions on * this item - * @throws coding_exception If data wasn't loaded */ public function get_full_information($modinfo=null) { $this->require_data(); @@ -302,7 +350,12 @@ WHERE * - This does not take account of the viewhiddenactivities capability. * That should apply later. * - * @param string &$information If the item has availability restrictions, + * @global object + * @global object + * @uses COMPLETION_COMPLETE + * @uses COMPLETION_COMPLETE_FAIL + * @uses COMPLETION_COMPLETE_PASS + * @param string $information If the item has availability restrictions, * a string that describes the conditions will be stored in this variable; * if this variable is set blank, that means don't display anything * @param bool $grabthelot Performance hint: if true, caches information @@ -313,7 +366,6 @@ WHERE * calling recursively from inside get_fast_modinfo. The value supplied * here must include list of all CMs with 'id' and 'name' * @return bool True if this item is available to the user, false otherwise - * @throws coding_exception If data wasn't loaded */ public function is_available(&$information, $grabthelot=false, $userid=0, $modinfo=null) { $this->require_data(); @@ -423,6 +475,7 @@ WHERE /** * Shows a time either as a date (if it falls exactly on the day) or * a full date and time, according to user's timezone. + * * @param int $time Time * @param bool $until True if this date should be treated as the second of * an inclusive pair - if so the time will be shown unless date is 23:59:59. @@ -458,7 +511,8 @@ WHERE /** * Internal function cheks that data was loaded. - * @throws coding_exception If data wasn't loaded + * + * @return void throws coding_exception If data wasn't loaded */ private function require_data() { if (!$this->gotdata) { @@ -472,6 +526,9 @@ WHERE * the user, because gradebook rules might prohibit that. It may be a * non-final score subject to adjustment later. * + * @global object + * @global object + * @global object * @param int $gradeitemid Grade item ID we're interested in * @param bool $grabthelot If true, grabs all scores for current user on * this course, so that later ones come from cache @@ -548,7 +605,11 @@ WHERE } } - /** For testing only. Wipes information cached in user session. */ + /** + * For testing only. Wipes information cached in user session. + * + * @global object + */ static function wipe_session_cache() { global $SESSION; unset($SESSION->gradescorecache); @@ -560,8 +621,8 @@ WHERE * course_modules_availability table based on the module form data. * * @param object $cm Course-module with as much data as necessary, min id - * @param unknown_type $fromform - * @param unknown_type $wipefirst + * @param object $fromform + * @param bool $wipefirst Defaults to true */ public static function update_cm_from_form($cm, $fromform, $wipefirst=true) { $ci=new condition_info($cm, CONDITION_MISSING_EVERYTHING, false); @@ -587,6 +648,8 @@ WHERE /** * Used in course/lib.php because we need to disable the completion JS if * a completion value affects a conditional activity. + * + * @global object * @param object $course Moodle course object * @param object $cm Moodle course-module * @return bool True if this is used in a condition, false otherwise diff --git a/lib/cssconstants.php b/lib/cssconstants.php index 6fbb0253eb..382d699db6 100644 --- a/lib/cssconstants.php +++ b/lib/cssconstants.php @@ -1,68 +1,89 @@ -. -/****************************************************************************** - - Plug in constants/variables - See MDL-6798 for details - - Information from Urs Hunkler: - - - More flexible themes with CSS constants: An option for Moodle retro themes and easy colour palette variants. - - I adopted Shaun Inman's "CSS Server-side Constants" to Moodle: http://www.shauninman.com/post/heap/2005/08/09/css_constants - - With setting "cssconstants" to true in "config.php" you activate the CSS constants. If "cssconstants" is missing or set to "false" the - replacement function is not used. - - $THEME->cssconstants = true; - /// By setting this to true, you will be able to use CSS constants - - - The constant definitions are written into a separate CSS file named like "constants.css" and loaded first in config.php. You can use constants for any CSS properties. The constant definition looks like: - -@server constants { - fontColor: #3a2830; - aLink: #116699; - aVisited: #AA2200; - aHover: #779911; - pageBackground: #FFFFFF; - backgroundColor: #EEEEEE; - backgroundSideblockHeader: #a8a4e9; - fontcolorSideblockHeader: #222222; - color1: #98818b; - color2: #bd807b; - color3: #f9d1d7; - color4: #e8d4d8; -} - - - -The lines in the CSS files using CSS constants look like: - -body { - font-size: 100%; - background-color: pageBackground; - color: fontColor; - font-family: 'Bitstream Vera Serif', georgia, times, serif; - margin: 0; - padding: 0; -} -div#page { - margin: 0 10px; - padding-top: 5px; - border-top-width: 10px; - border-top-style: solid; - border-top-color: color3; -} -div.clearer { - clear: both; -} -a:link { - color: aLink; -} - -******************************************************************************/ +/** + * Plug in constants/variables - See MDL-6798 for details + * + * Information from Urs Hunkler: + * + * + * More flexible themes with CSS constants: An option for Moodle retro themes and easy colour palette variants. + * + * I adopted Shaun Inman's "CSS Server-side Constants" to Moodle: http://www.shauninman.com/post/heap/2005/08/09/css_constants + * + * With setting "cssconstants" to true in "config.php" you activate the CSS constants. If "cssconstants" is missing or set to "false" the + * replacement function is not used. + * + * $THEME->cssconstants = true; + * By setting this to true, you will be able to use CSS constants + * + * The constant definitions are written into a separate CSS file named like "constants.css" and loaded first in config.php. You can use constants for any CSS properties. The constant definition looks like: + * + * \@server constants { + * fontColor: #3a2830; + * aLink: #116699; + * aVisited: #AA2200; + * aHover: #779911; + * pageBackground: #FFFFFF; + * backgroundColor: #EEEEEE; + * backgroundSideblockHeader: #a8a4e9; + * fontcolorSideblockHeader: #222222; + * color1: #98818b; + * color2: #bd807b; + * color3: #f9d1d7; + * color4: #e8d4d8; + * } + * + * + * The lines in the CSS files using CSS constants look like: + * + * body { + * font-size: 100%; + * background-color: pageBackground; + * color: fontColor; + * font-family: 'Bitstream Vera Serif', georgia, times, serif; + * margin: 0; + * padding: 0; + * } + * div#page { + * margin: 0 10px; + * padding-top: 5px; + * border-top-width: 10px; + * border-top-style: solid; + * border-top-color: color3; + * } + * div.clearer { + * clear: both; + * } + * a:link { + * color: aLink; + * } + * + * + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + /** + * Replaces CSS Constants within CSS string + * + * @param string $css + * @return string + */ function replace_cssconstants($css) { if (preg_match_all("/@server\s+(?:variables|constants)\s*\{\s*([^\}]+)\s*\}\s*/i",$css,$matches)) { $variables = array(); @@ -78,5 +99,4 @@ function replace_cssconstants($css) { return ($css); } -// vim:autoindent:expandtab:shiftwidth=4:tabstop=4:tw=140: ?> diff --git a/lib/csvlib.class.php b/lib/csvlib.class.php index ebfff5548c..cebe02e589 100644 --- a/lib/csvlib.class.php +++ b/lib/csvlib.class.php @@ -1,24 +1,61 @@ . + +/** + * This is a one-line short description of the file + * + * You can have a rather longer description of the file as well, + * if you like, and it can span multiple lines. + * + * @copyright Petr Skoda + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package moodlecore */ /** * Utitily class for importing of CSV files. + * @copyright Petr Skoda + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package moodlecore */ class csv_import_reader { + /** + * @var int import identifier + */ var $_iid; + /** + * @var string which script imports? + */ var $_type; + /** + * @var string|null Null if ok, error msg otherwise + */ var $_error; - var $_columns; //cached columns + /** + * @var array cached columns + */ + var $_columns; + /** + * @var object file handle used during import + */ var $_fp; /** * Contructor + * * @param int $iid import identifier * @param string $type which script imports? */ @@ -29,11 +66,14 @@ class csv_import_reader { /** * Parse this content - * @param string &$content passed by ref for memory reasons, unset after return + * + * @global object + * @global object + * @param string $content passed by ref for memory reasons, unset after return * @param string $encoding content encoding * @param string $delimiter_name separator (comma, semicolon, colon, cfg) * @param string $column_validation name of function for columns validation, must have one param $columns - * @return false if error, count of data lines if ok; use get_error() to get error string + * @return bool false if error, count of data lines if ok; use get_error() to get error string */ function load_csv_content(&$content, $encoding, $delimiter_name, $column_validation=null) { global $USER, $CFG; @@ -108,6 +148,7 @@ class csv_import_reader { /** * Returns list of columns + * * @return array */ function get_columns() { @@ -133,6 +174,10 @@ class csv_import_reader { /** * Init iterator. + * + * @global object + * @global object + * @return bool Success */ function init() { global $CFG, $USER; @@ -153,7 +198,8 @@ class csv_import_reader { /** * Get next line - * @return array of values + * + * @return mixed false, or an array of values */ function next() { if (empty($this->_fp) or feof($this->_fp)) { @@ -168,6 +214,8 @@ class csv_import_reader { /** * Release iteration related resources + * + * @return void */ function close() { if (!empty($this->_fp)) { @@ -178,6 +226,7 @@ class csv_import_reader { /** * Get last error + * * @return string error text of null if none */ function get_error() { @@ -186,8 +235,10 @@ class csv_import_reader { /** * Cleanup temporary data - * @static if $full=true - * @param boolean true menasdo a full cleanup - all sessions for current user, false only the active iid + * + * @global object + * @global object + * @param boolean $full true means do a full cleanup - all sessions for current user, false only the active iid */ function cleanup($full=false) { global $USER, $CFG; @@ -201,7 +252,7 @@ class csv_import_reader { /** * Get list of cvs delimiters - * @static + * * @return array suitable for selection box */ function get_delimiter_list() { @@ -214,9 +265,9 @@ class csv_import_reader { /** * Get delimiter character - * @static + * * @param string separator name - * @return char delimiter char + * @return string delimiter char */ function get_delimiter($delimiter_name) { switch ($delimiter_name) { @@ -230,9 +281,10 @@ class csv_import_reader { /** * Get encoded delimiter character - * @static + * + * @global object * @param string separator name - * @return char encoded delimiter char + * @return string encoded delimiter char */ function get_encoded_delimiter($delimiter_name) { global $CFG; @@ -245,7 +297,8 @@ class csv_import_reader { /** * Create new import id - * @static + * + * @global object * @param string who imports? * @return int iid */ diff --git a/lib/customcheckslib.php b/lib/customcheckslib.php index ead8e83ce8..af735bc5d2 100644 --- a/lib/customcheckslib.php +++ b/lib/customcheckslib.php @@ -1,44 +1,44 @@ -. -/////////////////////////////////////////////////////////////////////////// -// // -// NOTICE OF COPYRIGHT // -// // -// Moodle - Modular Object-Oriented Dynamic Learning Environment // -// http://moodle.com // -// // -// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // -// (C) 2001-3001 Eloy Lafuente (stronk7) http://contiento.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 library contains a collection of functions able to perform -/// some custom checks executed by environmental tests (automatically -/// executed on install & upgrade and under petition in the admin block). -/// -/// Any function in this library must return: -/// - null: if the test isn't relevant and must not be showed (ignored) -/// - environment_results object with the status set to: -/// - true: if passed -/// - false: if failed +/** + * This is a one-line short description of the file + * + * This library contains a collection of functions able to perform + * some custom checks executed by environmental tests (automatically + * executed on install & upgrade and under petition in the admin block). + * + * Any function in this library must return: + * - null: if the test isn't relevant and must not be showed (ignored) + * - environment_results object with the status set to: + * - true: if passed + * - false: if failed + * + * Major Contributor: Eloy Lafuente (stronk7) {@link http://contiento.com} + * + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ /** * This function will look for the risky PHP setting register_globals * in order to inform about. MDL-12914 * - * @param $result the environment_results object to be modified + * @param object $result the environment_results object to be modified * @return mixed null if the test is irrelevant or environment_results object with * status set to true (test passed) or false (test failed) */ diff --git a/lib/datalib.php b/lib/datalib.php index d37bffd1da..5ae2fcb272 100644 --- a/lib/datalib.php +++ b/lib/datalib.php @@ -1,4 +1,19 @@ -. /** * Library of functions for database manipulation. @@ -6,25 +21,35 @@ * Other main libraries: * - weblib.php - functions that produce web output * - moodlelib.php - general-purpose Moodle functions - * @author Martin Dougiamas and many others - * @license http://www.gnu.org/copyleft/gpl.html GNU Public License - * @package moodlecore + * + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ -define('MAX_COURSES_IN_CATEGORY', 10000); // MAX_COURSES_IN_CATEGORY * MAX_COURSE_CATEGORIES must not be more than max integer! + /** + * The maximum courses in a category + * MAX_COURSES_IN_CATEGORY * MAX_COURSE_CATEGORIES must not be more than max integer! + */ +define('MAX_COURSES_IN_CATEGORY', 10000); +/** + * The maximum number of course categories + * MAX_COURSES_IN_CATEGORY * MAX_COURSE_CATEGORIES must not be more than max integer! + */ define('MAX_COURSE_CATEGORIES', 10000); - /// Some constants - define('LASTACCESS_UPDATE_SECS', 60); /// Number of seconds to wait before - /// updating lastaccess information in DB. - -/// USER DATABASE //////////////////////////////////////////////// + /** + * Number of seconds to wait before updating lastaccess information in DB. + */ + define('LASTACCESS_UPDATE_SECS', 60); /** * Returns $user object of the main admin user * primary admin = admin with lowest role_assignment id among admins - * @uses $CFG - * @return object(admin) An associative array representing the admin user. + * + * @global object + * @static object $myadmin + * @return object An associative array representing the admin user. */ function get_admin () { @@ -49,8 +74,8 @@ function get_admin () { * Returns list of all admins, using 1 DB query. It depends on DB schema v1.7 * but does not depend on the v1.9 datastructures (context.path, etc). * - * @uses $CFG - * @return object + * @global object + * @return array */ function get_admins() { global $DB; @@ -73,7 +98,13 @@ function get_admins() { return $DB->get_records_sql($sql, $params); } - +/** + * Get all of the courses in a given meta course + * + * @global object + * @param int $metacourseid The metacourse id + * @return array + */ function get_courses_in_metacourse($metacourseid) { global $DB; @@ -86,6 +117,14 @@ function get_courses_in_metacourse($metacourseid) { return $DB->get_records_sql($sql, $params); } +/** + * @todo Document this function + * + * @global object + * @uses SITEID + * @param int $metacourseid + * @return array + */ function get_courses_notin_metacourse($metacourseid) { global $DB; @@ -106,6 +145,16 @@ function get_courses_notin_metacourse($metacourseid) { return $DB->get_records_sql($sql, $params); } +/** + * @todo Document this function + * + * This function is nearly identical to {@link get_courses_notin_metacourse()} + * + * @global object + * @uses SITEID + * @param int $metacourseid + * @return int The count + */ function count_courses_notin_metacourse($metacourseid) { global $DB; @@ -131,12 +180,16 @@ function count_courses_notin_metacourse($metacourseid) { * If $coursid specifies the site course then this function searches * through all undeleted and confirmed users * + * @global object + * @uses SITEID + * @uses SQL_PARAMS_NAMED + * @uses CONTEXT_COURSE * @param int $courseid The course in question. * @param int $groupid The group in question. - * @param string $searchtext ? - * @param string $sort ? - * @param array $exceptions ? - * @return object + * @param string $searchtext The string to search for + * @param string $sort A field to sort by + * @param array $exceptions A list of IDs to ignore, eg 2,4,5,8,9,10 + * @return array */ function search_users($courseid, $groupid, $searchtext, $sort='', array $exceptions=null) { global $DB; @@ -199,18 +252,21 @@ function search_users($courseid, $groupid, $searchtext, $sort='', array $excepti /** * Returns a subset of users * - * @uses $CFG + * @global object + * @uses DEBUG_DEVELOPER + * @uses SQL_PARAMS_NAMED * @param bool $get If false then only a count of the records is returned * @param string $search A simple string to search for * @param bool $confirmed A switch to allow/disallow unconfirmed users - * @param array(int) $exceptions A list of IDs to ignore, eg 2,4,5,8,9,10 + * @param array $exceptions A list of IDs to ignore, eg 2,4,5,8,9,10 * @param string $sort A SQL snippet for the sorting criteria to use - * @param string $firstinitial ? - * @param string $lastinitial ? - * @param string $page ? - * @param string $recordsperpage ? + * @param string $firstinitial Users whose first name starts with $firstinitial + * @param string $lastinitial Users whose last name starts with $lastinitial + * @param string $page The page or records to return + * @param string $recordsperpage The number of records to return per page * @param string $fields A comma separated list of fields to be returned from the chosen table. - * @return object|false|int {@link $USER} records unless get is false in which case the integer count of the records found is returned. False is returned if an error is encountered. + * @return array|int|bool {@link $USER} records unless get is false in which case the integer count of the records found is returned. + * False is returned if an error is encountered. */ function get_users($get=true, $search='', $confirmed=false, array $exceptions=null, $sort='firstname ASC', $firstinitial='', $lastinitial='', $page='', $recordsperpage='', $fields='*', $extraselect='', array $extraparams=null) { @@ -270,19 +326,18 @@ function get_users($get=true, $search='', $confirmed=false, array $exceptions=nu /** - * shortdesc (optional) - * - * longdesc - * - * @param string $sort ? - * @param string $dir ? - * @param int $categoryid ? - * @param int $categoryid ? - * @param string $search ? - * @param string $firstinitial ? - * @param string $lastinitial ? - * @returnobject {@link $USER} records * @todo Finish documenting this function + * + * @param string $sort An SQL field to sort by + * @param string $dir The sort direction ASC|DESC + * @param int $page The page or records to return + * @param int $recordsperpage The number of records to return per page + * @param string $search A simple string to search for + * @param string $firstinitial Users whose first name starts with $firstinitial + * @param string $lastinitial Users whose last name starts with $lastinitial + * @param string $extraselect An additional SQL select statement to append to the query + * @param array $extraparams Additional parameters to use for the above $extraselect + * @return array Array of {@link $USER} records */ function get_users_listing($sort='lastaccess', $dir='ASC', $page=0, $recordsperpage=0, @@ -333,6 +388,7 @@ function get_users_listing($sort='lastaccess', $dir='ASC', $page=0, $recordsperp /** * Full list of users that have confirmed their accounts. * + * @global object * @return array of unconfirmed users */ function get_users_confirmed() { @@ -349,7 +405,9 @@ function get_users_confirmed() { /** * Returns $course object of the top-level site. * - * @return course A {@link $COURSE} object for the site + * @global object + * @global object + * @return bool|object A {@link $COURSE} object for the site */ function get_site() { global $SITE, $DB; @@ -373,8 +431,14 @@ function get_site() { * we are using distinct. You almost _NEVER_ need all the fields * in such a large SELECT * - * @param type description - * @return array of courses + * @global object + * @global object + * @global object + * @uses CONTEXT_COURSE + * @param string|int $categoryid Either a category id or 'all' for everything + * @param string $sort A field and direction to sort by + * @param string $fields The additional fields to return + * @return array Array of courses */ function get_courses($categoryid="all", $sort="c.sortorder ASC", $fields="c.*") { @@ -434,8 +498,17 @@ function get_courses($categoryid="all", $sort="c.sortorder ASC", $fields="c.*") * we are using distinct. You almost _NEVER_ need all the fields * in such a large SELECT * - * @param type description - * @return array of courses + * @global object + * @global object + * @global object + * @uses CONTEXT_COURSE + * @param string|int $categoryid Either a category id or 'all' for everything + * @param string $sort A field and direction to sort by + * @param string $fields The additional fields to return + * @param int $totalcount Reference for the number of courses + * @param string $limitfrom The course to start from + * @param string $limitnum The number of courses to limit to + * @return array Array of courses */ function get_courses_page($categoryid="all", $sort="c.sortorder ASC", $fields="c.*", &$totalcount, $limitfrom="", $limitnum="") { @@ -504,6 +577,17 @@ function get_courses_page($categoryid="all", $sort="c.sortorder ASC", $fields="c * - $course->managers - array containing RA objects that include a $user obj * with the minimal fields needed for fullname() * + * @global object + * @global object + * @global object + * @uses CONTEXT_COURSE + * @uses CONTEXT_SYSTEM + * @uses CONTEXT_COURSECAT + * @uses SITEID + * @param int|string $categoryid Either the categoryid for the courses or 'all' + * @param string $sort A SQL sort field and direction + * @param array $fields An array of additional fields to fetch + * @return array */ function get_courses_wmanagers($categoryid=0, $sort="c.sortorder ASC", $fields=array()) { /* @@ -728,13 +812,18 @@ function get_courses_wmanagers($categoryid=0, $sort="c.sortorder ASC", $fields=a * - the course records have $c->context which is a fully * valid context object. Saves you a query per course! * - * @uses $CFG,$USER + * @global object + * @global object + * @global object + * @uses CONTEXT_SYSTEM + * @uses CONTEXT_COURSE + * @uses CONTEXT_COURSECAT * @param int $userid The user of interest * @param string $sort the sortorder in the course table - * @param array $fields - names of _additional_ fields to return (also accepts a string) + * @param array $fields names of _additional_ fields to return (also accepts a string) * @param bool $doanything True if using the doanything flag * @param int $limit Maximum number of records to return, or 0 for unlimited - * @return array {@link $COURSE} of course objects + * @return array Array of {@link $COURSE} of course objects */ function get_my_courses($userid, $sort='visible DESC,sortorder ASC', $fields=NULL, $doanything=false,$limit=0) { global $CFG, $USER, $DB; @@ -992,12 +1081,13 @@ function get_my_courses($userid, $sort='visible DESC,sortorder ASC', $fields=NUL /** * A list of courses that match a search * - * @uses $CFG - * @param array $searchterms ? - * @param string $sort ? - * @param int $page ? - * @param int $recordsperpage ? - * @param int $totalcount Passed in by reference. ? + * @global object + * @global object + * @param array $searchterms An array of search criteria + * @param string $sort A field and direction to sort by + * @param int $page The page number to get + * @param int $recordsperpage The number of records per page + * @param int $totalcount Passed in by reference. * @return object {@link $COURSE} records */ function get_courses_search($searchterms, $sort='fullname ASC', $page=0, $recordsperpage=50, &$totalcount) { @@ -1104,7 +1194,8 @@ function get_courses_search($searchterms, $sort='fullname ASC', $page=0, $record * a "shallow" resultset. Pass false to $shallow and it will return all * the child categories as well. * - * + * @global object + * @uses CONTEXT_COURSECAT * @param string $parent The parent category if any * @param string $sort the sortorder * @param bool $shallow - set to false to get the children too @@ -1173,7 +1264,9 @@ function get_categories($parent='none', $sort=NULL, $shallow=true) { /** * Returns an array of category ids of all the subcategories for a given * category. - * @param $catid - The id of the category whose subcategories we want to find. + * + * @global object + * @param int $catid - The id of the category whose subcategories we want to find. * @return array of category ids. */ function get_all_subcategories($catid) { @@ -1192,6 +1285,11 @@ function get_all_subcategories($catid) { /** * Return specified category, default if given does not exist + * + * @global object + * @uses MAX_COURSES_IN_CATEGORY + * @uses CONTEXT_COURSECAT + * @uses SYSCONTEXTID * @param int $catid course category id * @return object caregory */ @@ -1232,6 +1330,14 @@ function get_course_category($catid=0) { /** * Fixes course category and course sortorder, also verifies category and course parents and paths. * (circular references are not fixed) + * + * @global object + * @global object + * @uses MAX_COURSES_IN_CATEGORY + * @uses MAX_COURSE_CATEGORIES + * @uses SITEID + * @uses CONTEXT_COURSE + * @return void */ function fix_course_sortorder() { global $DB, $SITE; @@ -1398,6 +1504,19 @@ function fix_course_sortorder() { /** * Internal recursive category verification function, do not use directly! + * + * @todo Document the arguments of this function better + * + * @global object + * @uses MAX_COURSES_IN_CATEGORY + * @uses CONTEXT_COURSECAT + * @param array $children + * @param int $sortorder + * @param string $parent + * @param int $depth + * @param string $path + * @param array $fixcontexts + * @return void */ function _fix_course_cats($children, &$sortorder, $parent, $depth, $path, &$fixcontexts) { global $DB; @@ -1434,8 +1553,10 @@ function _fix_course_cats($children, &$sortorder, $parent, $depth, $path, &$fixc * List of remote courses that a user has access to via MNET. * Works only on the IDP * - * @uses $CFG, $USER - * @return array {@link $COURSE} of course objects + * @global object + * @global object + * @param int @userid The user id to get remote courses for + * @return array Array of {@link $COURSE} of course objects */ function get_my_remotecourses($userid=0) { global $DB, $USER; @@ -1459,8 +1580,9 @@ function get_my_remotecourses($userid=0) { * List of remote hosts that a user has access to via MNET. * Works on the SP * - * @uses $CFG, $USER - * @return array of host objects + * @global object + * @global object + * @return array|bool Array of host objects or false */ function get_my_remotehosts() { global $CFG, $USER; @@ -1482,6 +1604,10 @@ function get_my_remotehosts() { * strings and files is a bit odd, but this is because we * need to maintain backward compatibility with many different * existing language translations and older sites. + * + * @global object + * @global object + * @return void */ function make_default_scale() { global $CFG, $DB; @@ -1526,9 +1652,9 @@ function make_default_scale() { /** * Returns a menu of all available scales from the site as well as the given course * - * @uses $CFG + * @global object * @param int $courseid The id of the course as found in the 'course' table. - * @return object + * @return array */ function get_scales_menu($courseid=0) { global $DB; @@ -1553,8 +1679,9 @@ function get_scales_menu($courseid=0) { /** * Given a set of timezone records, put them in the database, replacing what is there * - * @uses $CFG + * @global object * @param array $timezones An array of timezone records + * @return void */ function update_timezone_records($timezones) { global $DB; @@ -1577,8 +1704,9 @@ function update_timezone_records($timezones) { /** * Just gets a raw list of all modules in a course * + * @global object * @param int $courseid The id of the course as found in the 'course' table. - * @return object + * @return array */ function get_course_mods($courseid) { global $DB; @@ -1597,11 +1725,12 @@ function get_course_mods($courseid) { /** * Given an id of a course module, finds the coursemodule description * + * @global object * @param string $modulename name of module type, eg. resource, assignment,... (optional, slower and less safe if not specified) * @param int $cmid course module id (id in course_modules table) * @param int $courseid optional course id for extra validation * @param bool $sectionnum include relative section number (0,1,2 ...) - * @return object course module instance with instance and module name + * @return array Array of results */ function get_coursemodule_from_id($modulename, $cmid, $courseid=0, $sectionnum=false) { global $DB; @@ -1647,11 +1776,12 @@ function get_coursemodule_from_id($modulename, $cmid, $courseid=0, $sectionnum=f /** * Given an instance number of a module, finds the coursemodule description * + * @global object * @param string $modulename name of module type, eg. resource, assignment,... * @param int $instance module instance number (id in resource, assignment etc. table) * @param int $courseid optional course id for extra validation * @param bool $sectionnum include relative section number (0,1,2 ...) - * @return object course module instance with instance and module name + * @return array Array of results */ function get_coursemodule_from_instance($modulename, $instance, $courseid=0, $sectionnum=false) { global $DB; @@ -1685,10 +1815,11 @@ function get_coursemodule_from_instance($modulename, $instance, $courseid=0, $se /** * Returns all course modules of given activity in course - * @param string $modulename (forum, quiz, etc.) - * @param int $courseid + * + * @param string $modulename The module name (forum, quiz, etc.) + * @param int $courseid The course id to get modules for * @param string $extrafields extra fields starting with m. - * @return array of cm objects, false if not found or error + * @return array Array of results */ function get_coursemodules_in_course($modulename, $courseid, $extrafields='') { global $DB; @@ -1719,8 +1850,12 @@ function get_coursemodules_in_course($modulename, $courseid, $extrafields='') { * The returned objects includle the columns cw.section, cm.visible, * cm.groupmode and cm.groupingid, cm.groupmembersonly, and are indexed by cm.id. * + * @global object + * @global object * @param string $modulename The name of the module to get instances for * @param array $courses an array of course objects. + * @param int $userid + * @param int $includeinvisible * @return array of module instance objects, including some extra fields from the course_modules * and course_sections tables, or an empty array if an error occurred. */ @@ -1784,10 +1919,14 @@ function get_all_instances_in_courses($modulename, $courses, $userid=NULL, $incl * The returned objects includle the columns cw.section, cm.visible, * cm.groupmode and cm.groupingid, cm.groupmembersonly, and are indexed by cm.id. * + * Simply calls {@link all_instances_in_courses()} with a single provided course + * * @param string $modulename The name of the module to get instances for * @param object $course The course obect. * @return array of module instance objects, including some extra fields from the course_modules * and course_sections tables, or an empty array if an error occurred. + * @param int $userid + * @param int $includeinvisible */ function get_all_instances_in_course($modulename, $course, $userid=NULL, $includeinvisible=false) { return get_all_instances_in_courses($modulename, array($course->id => $course), $userid, $includeinvisible); @@ -1801,9 +1940,11 @@ function get_all_instances_in_course($modulename, $course, $userid=NULL, $includ * and the module's type (eg "forum") returns whether the object * is visible or not, groupmembersonly visibility not tested * + * @global object + * @param $moduletype Name of the module eg 'forum' * @param $module Object which is the instance of the module - * @return bool + * @return bool Success */ function instance_is_visible($moduletype, $module) { global $DB; @@ -1829,9 +1970,14 @@ function instance_is_visible($moduletype, $module) { * Determine whether a course module is visible within a course, * this is different from instance_is_visible() - faster and visibility for user * + * @global object + * @global object + * @uses DEBUG_DEVELOPER + * @uses CONTEXT_MODULE + * @uses CONDITION_MISSING_EXTRATABLE * @param object $cm object * @param int $userid empty means current user - * @return bool + * @return bool Success */ function coursemodule_visible_for_user($cm, $userid=0) { global $USER,$CFG; @@ -1871,10 +2017,12 @@ function coursemodule_visible_for_user($cm, $userid=0) { * than web server hits, and provide a way to easily reconstruct what * any particular student has been doing. * - * @uses $CFG - * @uses $USER - * @uses $REMOTE_ADDR + * @global object + * @global object + * @global object * @uses SITEID + * @uses DEBUG_DEVELOPER + * @uses DEBUG_ALL * @param int $courseid The course id * @param string $module The module name - e.g. forum, journal, resource, course, user etc * @param string $action 'view', 'update', 'add' or 'delete', possibly followed by another word to clarify. @@ -1882,6 +2030,7 @@ function coursemodule_visible_for_user($cm, $userid=0) { * @param string $info Additional description information * @param string $cm The course_module->id if there is one * @param string $user If log regards $user other than $USER + * @return void */ function add_to_log($courseid, $module, $action, $url='', $info='', $cm=0, $user=0) { // Note that this function intentionally does not follow the normal Moodle DB access idioms. @@ -1965,6 +2114,11 @@ function add_to_log($courseid, $module, $action, $url='', $info='', $cm=0, $user /** * Store user last access times - called when use enters a course or site * + * @global object + * @global object + * @global object + * @uses LASTACCESS_UPDATE_SECS + * @uses SITEID * @param int $courseid, empty means site * @return void */ @@ -2030,6 +2184,9 @@ function user_accesstime_log($courseid=0) { /** * Select all log records based on SQL criteria * + * @todo Finish documenting this function + * + * @global object * @param string $select SQL select criteria * @param array $params named sql type params * @param string $order SQL order by clause to sort the records returned @@ -2037,7 +2194,6 @@ function user_accesstime_log($courseid=0) { * @param int $limitnum ? * @param int $totalcount Passed in by reference. * @return object - * @todo Finish documenting this function */ function get_logs($select, array $params=null, $order='l.time DESC', $limitfrom='', $limitnum='', &$totalcount) { global $DB; @@ -2072,12 +2228,13 @@ function get_logs($select, array $params=null, $order='l.time DESC', $limitfrom= /** * Select all log records for a given course and user * - * @uses $CFG + * @todo Finish documenting this function + * + * @global object * @uses DAYSECS * @param int $userid The id of the user as found in the 'user' table. * @param int $courseid The id of the course as found in the 'course' table. * @param string $coursestart ? - * @todo Finish documenting this function */ function get_logs_usercourse($userid, $courseid, $coursestart) { global $DB; @@ -2102,13 +2259,12 @@ function get_logs_usercourse($userid, $courseid, $coursestart) { /** * Select all log records for a given course, user, and day * - * @uses $CFG + * @global object * @uses HOURSECS * @param int $userid The id of the user as found in the 'user' table. * @param int $courseid The id of the course as found in the 'course' table. * @param string $daystart ? * @return object - * @todo Finish documenting this function */ function get_logs_userday($userid, $courseid, $daystart) { global $DB; @@ -2138,6 +2294,8 @@ function get_logs_userday($userid, $courseid, $daystart) { * number of accounts. For non-admins, only the attempts on the given user * are shown. * + * @global object + * @uses CONTEXT_SYSTEM * @param string $mode Either 'admin', 'teacher' or 'everybody' * @param string $username The username we are searching for * @param string $lastlogin The date from which we are searching @@ -2173,6 +2331,7 @@ function count_login_failures($mode, $username, $lastlogin) { * Mostly just used for debugging. * * @param mixed $object The data to be printed + * @return void OUtput is echo'd */ function print_object($object) { echo '
' . htmlspecialchars(print_r($object,true)) . '
'; @@ -2199,7 +2358,10 @@ function print_object($object) { * - Do NOT call this over many courses as it'll generate * DB traffic. Instead, see what get_my_courses() does. * - * @param mixed $object A course object + * @global object + * @global object + * @staticvar array $mycache + * @param object $course A course object * @return bool */ function course_parent_visible($course = null) { @@ -2251,8 +2413,9 @@ function course_parent_visible($course = null) { * Any script can avoid calls to this function by defining XMLDB_SKIP_DEBUG_HOOK before * using XMLDB classes. Obviously, also, if this function doesn't exist, it isn't invoked ;-) * - * @param $message string contains the error message - * @param $object object XMLDB object that fired the debug + * @uses DEBUG_DEVELOPER + * @param string $message string contains the error message + * @param object $object object XMLDB object that fired the debug */ function xmldb_debug($message, $object) { @@ -2260,6 +2423,8 @@ function xmldb_debug($message, $object) { } /** + * @global object + * @uses CONTEXT_COURSECAT * @return boolean Whether the user can create courses in any category in the system. */ function user_can_create_courses() { diff --git a/lib/ddllib.php b/lib/ddllib.php index a07ed3f99d..6636bdffd8 100644 --- a/lib/ddllib.php +++ b/lib/ddllib.php @@ -1,57 +1,66 @@ -. -/// Add required library. +/** + * This library includes all the required functions used to handle the DB + * structure (DDL) independently of the underlying RDBMS in use. + * + * This library includes all the required functions used to handle the DB + * structure (DDL) independently of the underlying RDBMS in use. All the functions + * rely on the XMLDBDriver classes to be able to generate the correct SQL + * syntax needed by each DB. + * + * To define any structure to be created we'll use the schema defined + * by the XMLDB classes, for tables, fields, indexes, keys and other + * statements instead of direct handling of SQL sentences. + * + * This library should be used, exclusively, by the installation and + * upgrade process of Moodle. + * + * For further documentation, visit {@link http://docs.moodle.org/en/DDL_functions} + * + * Major Contributor: Eloy Lafuente (stronk7) {@link http://contiento.com} + * + * @package moodlecore + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +/** Add required library */ require_once($CFG->libdir.'/xmlize.php'); -/// Add required XMLDB constants +/** Add required XMLDB constants */ require_once($CFG->libdir.'/xmldb/xmldb_constants.php'); -/// Add required XMLDB DB classes +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_object.php'); +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_file.php'); +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_structure.php'); +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_table.php'); +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_field.php'); +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_key.php'); +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_index.php'); +/** Add required XMLDB DB classes */ require_once($CFG->libdir.'/xmldb/xmldb_statement.php'); require_once($CFG->libdir.'/ddl/sql_generator.php'); @@ -61,8 +70,16 @@ require_once($CFG->libdir.'/ddl/database_manager.php'); /** * DDL exception class, use instead of error() and "return false;" in ddl code. + * + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package moodlecore */ class ddl_exception extends moodle_exception { + /** + * @param string $errorcode + * @param string $debuginfo + */ function __construct($errorcode, $a=NULL, $debuginfo=null) { parent::__construct($errorcode, '', '', $a, $debuginfo); } @@ -70,8 +87,16 @@ class ddl_exception extends moodle_exception { /** * Table does not exist problem exception + * + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package moodlecore */ class ddl_table_missing_exception extends ddl_exception { + /** + * @param string $tablename + * @param string $debuginfo + */ function __construct($tablename, $debuginfo=null) { parent::__construct('ddltablenotexist', $tablename, $debuginfo); } @@ -79,8 +104,17 @@ class ddl_table_missing_exception extends ddl_exception { /** * Table does not exist problem exception + * + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package moodlecore */ class ddl_field_missing_exception extends ddl_exception { + /** + * @param string $fieldname + * @param string $tablename + * @param string $debuginfo + */ function __construct($fieldname, $tablename, $debuginfo=null) { $a = new object(); $a->fieldname = $fieldname; @@ -91,11 +125,19 @@ class ddl_field_missing_exception extends ddl_exception { /** * Error during changing db structure + * + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package moodlecore */ class ddl_change_structure_exception extends ddl_exception { + /** @var string */ public $error; public $sql; - + /** + * @param string $error + * @param string $sql + */ function __construct($error, $sql=null) { $this->error = $error; $this->sql = $sql; -- 2.39.5