diff --git a/lib/accesslib.php b/lib/accesslib.php index 11e321b75e8..bd45588f988 100644 --- a/lib/accesslib.php +++ b/lib/accesslib.php @@ -1529,10 +1529,10 @@ function unassign_capability($capability, $roleid, $contextid = null) { * It just checks for permissions and overrides. * Use get_roles_with_cap_in_context() if resolution is required. * - * @param string $capability - capability name (string) - * @param string $permission - optional, the permission defined for this capability + * @param string $capability capability name (string) + * @param string $permission optional, the permission defined for this capability * either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any. - * @param stdClass $context, null means any + * @param stdClass $context null means any * @return array of role records */ function get_roles_with_capability($capability, $permission = null, $context = null) { @@ -1745,7 +1745,7 @@ function role_unassign_all(array $params, $subcontexts = false, $includemanual = if ($context = context::instance_by_id($ra->contextid, IGNORE_MISSING)) { // this is a bit expensive but necessary $context->mark_dirty(); - /// If the user is the current user, then do full reload of capabilities too. + // If the user is the current user, then do full reload of capabilities too. if (!empty($USER->id) && $USER->id == $ra->userid) { reload_all_capabilities(); } @@ -1772,7 +1772,7 @@ function role_unassign_all(array $params, $subcontexts = false, $includemanual = $DB->delete_records('role_assignments', array('id'=>$ra->id)); // this is a bit expensive but necessary $context->mark_dirty(); - /// If the user is the current user, then do full reload of capabilities too. + // If the user is the current user, then do full reload of capabilities too. if (!empty($USER->id) && $USER->id == $ra->userid) { reload_all_capabilities(); } @@ -1891,7 +1891,7 @@ function is_guest(context $context, $user = null) { * @category access * * @param context $context - * @param int|stdClass $user, if null $USER is used + * @param int|stdClass $user if null $USER is used * @param string $withcapability extra capability name * @return bool */ @@ -1927,7 +1927,7 @@ function is_viewing(context $context, $user = null, $withcapability = '') { * @category access * * @param context $context - * @param int|stdClass $user, if null $USER is used, otherwise user object or id expected + * @param int|stdClass $user if null $USER is used, otherwise user object or id expected * @param string $withcapability extra capability name * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions * @return bool @@ -2632,10 +2632,10 @@ function get_capability_docs_link($capability) { * defaults) of a role used in capability overrides in contexts at a given * context. * - * @param context $context * @param int $roleid + * @param context $context * @param string $cap capability, optional, defaults to '' - * @return array of capabilities + * @return array Array of capabilities */ function role_context_capabilities($roleid, context $context, $cap = '') { global $DB; @@ -3521,7 +3521,7 @@ function get_users_by_capability(context $context, $capability, $fields = '', $s unset($n); } - /// ***** Set up default fields ****** + // ***** Set up default fields ****** if (empty($fields)) { if ($iscoursepage) { $fields = 'u.*, ul.timeaccess AS lastaccess'; @@ -3534,7 +3534,7 @@ function get_users_by_capability(context $context, $capability, $fields = '', $s } } - /// Set up default sort + // Set up default sort if (empty($sort)) { // default to course lastaccess or just lastaccess if ($iscoursepage) { $sort = 'ul.timeaccess'; @@ -3559,11 +3559,11 @@ function get_users_by_capability(context $context, $capability, $fields = '', $s } } - /// We never return deleted users or guest account. + // We never return deleted users or guest account. $wherecond[] = "u.deleted = 0 AND u.id <> :guestid"; $params['guestid'] = $CFG->siteguest; - /// Groups + // Groups if ($groups) { $groups = (array)$groups; list($grouptest, $grpparams) = $DB->get_in_or_equal($groups, SQL_PARAMS_NAMED, 'grp'); @@ -3582,7 +3582,7 @@ function get_users_by_capability(context $context, $capability, $fields = '', $s } } - /// User exceptions + // User exceptions if (!empty($exceptions)) { $exceptions = (array)$exceptions; list($exsql, $exparams) = $DB->get_in_or_equal($exceptions, SQL_PARAMS_NAMED, 'exc', false); @@ -3656,7 +3656,7 @@ function get_users_by_capability(context $context, $capability, $fields = '', $s } $joins = implode("\n", $joins); - /// Ok, let's get the users! + // Ok, let's get the users! $sql = "SELECT $fields FROM {user} u $joins @@ -4522,6 +4522,13 @@ function role_change_permission($roleid, $context, $capname, $permission) { /** * Basic moodle context abstraction class. * + * Google confirms that no other important framework is using "context" class, + * we could use something else like mcontext or moodle_context, but we need to type + * this very often which would be annoying and it would take too much space... + * + * This class is derived from stdClass for backwards compatibility with + * odl $context record that was returned from DML $DB->get_record() + * * @package core_access * @category access * @copyright Petr Skoda {@link http://skodak.org} @@ -4532,32 +4539,70 @@ function role_change_permission($roleid, $context, $capname, $permission) { * @property-read int $contextlevel CONTEXT_SYSTEM, CONTEXT_COURSE, etc. * @property-read int $instanceid id of related instance in each context * @property-read string $path path to context, starts with system context - * @property-read dept $depth + * @property-read int $depth */ abstract class context extends stdClass { - /* - * Google confirms that no other important framework is using "context" class, - * we could use something else like mcontext or moodle_context, but we need to type - * this very often which would be annoying and it would take too much space... - * - * This class is derived from stdClass for backwards compatibility with - * odl $context record that was returned from DML $DB->get_record() + /** + * The context id + * Can be accessed publicly through $context->id + * @var int */ - protected $_id; + + /** + * The context level + * Can be accessed publicly through $context->contextlevel + * @var int One of CONTEXT_* e.g. CONTEXT_COURSE, CONTEXT_MODULE + */ protected $_contextlevel; + + /** + * Id of the item this context is related to e.g. COURSE_CONTEXT => course.id + * Can be accessed publicly through $context->instanceid + * @var int + */ protected $_instanceid; + + /** + * The path to the context always starting from the system context + * Can be accessed publicly through $context->path + * @var string + */ protected $_path; + + /** + * The depth of the context in relation to parent contexts + * Can be accessed publicly through $context->depth + * @var int + */ protected $_depth; - /* context caching info */ - + /** + * @var array Context caching info + */ private static $cache_contextsbyid = array(); - private static $cache_contexts = array(); - protected static $cache_count = 0; // why do we do count contexts? Because count($array) is horribly slow for large arrays + /** + * @var array Context caching info + */ + private static $cache_contexts = array(); + + /** + * Context count + * Why do we do count contexts? Because count($array) is horribly slow for large arrays + * @var int + */ + protected static $cache_count = 0; + + /** + * @var array Context caching info + */ protected static $cache_preloaded = array(); + + /** + * @var context_system The system context once initialised + */ protected static $systemcontext = null; /** @@ -4691,7 +4736,7 @@ abstract class context extends stdClass { /** * Magic setter method, we do not want anybody to modify properties from the outside * @param string $name - * @param mixed @value + * @param mixed $value */ public function __set($name, $value) { debugging('Can not change context instance properties!'); @@ -4718,7 +4763,7 @@ abstract class context extends stdClass { /** * Full support for isset on our magic read only properties. - * @param $name + * @param string $name * @return bool */ public function __isset($name) { @@ -5171,7 +5216,7 @@ abstract class context extends stdClass { * Rebuild context paths and depths at context level. * * @static - * @param $force + * @param bool $force * @return void */ protected static function build_paths($force) { @@ -5271,6 +5316,9 @@ abstract class context extends stdClass { */ class context_helper extends context { + /** + * @var array An array mapping context levels to classes + */ private static $alllevels = array( CONTEXT_SYSTEM => 'context_system', CONTEXT_USER => 'context_user', @@ -5430,7 +5478,7 @@ class context_helper extends context { * To be used if you expect multiple queries for course activities... * * @static - * @param $courseid + * @param int $courseid */ public static function preload_course($courseid) { // Users can call this multiple times without doing any harm @@ -5702,7 +5750,7 @@ class context_system extends context { * Rebuild context paths and depths at system context level. * * @static - * @param $force + * @param bool $force */ protected static function build_paths($force) { global $DB; @@ -5887,7 +5935,7 @@ class context_user extends context { * Rebuild context paths and depths at user context level. * * @static - * @param $force + * @param bool $force */ protected static function build_paths($force) { global $DB; @@ -6077,7 +6125,7 @@ class context_coursecat extends context { * Rebuild context paths and depths at course category context level. * * @static - * @param $force + * @param bool $force */ protected static function build_paths($force) { global $DB; @@ -6300,7 +6348,7 @@ class context_course extends context { * Rebuild context paths and depths at course context level. * * @static - * @param $force + * @param bool $force */ protected static function build_paths($force) { global $DB; @@ -6554,7 +6602,7 @@ class context_module extends context { * Rebuild context paths and depths at module context level. * * @static - * @param $force + * @param bool $force */ protected static function build_paths($force) { global $DB; @@ -6771,7 +6819,7 @@ class context_block extends context { * Rebuild context paths and depths at block context level. * * @static - * @param $force + * @param bool $force */ protected static function build_paths($force) { global $DB; @@ -6937,7 +6985,7 @@ function get_parent_contextid(context $context) { * contexts ;-) * * @deprecated since 2.2, use $context->get_child_contexts() instead - * @param context $context. + * @param context $context * @return array Array of child records */ function get_child_contexts(context $context) { diff --git a/lib/setuplib.php b/lib/setuplib.php index 256c07c7557..ccbcad6d187 100644 --- a/lib/setuplib.php +++ b/lib/setuplib.php @@ -1,5 +1,4 @@ . - /** * These functions are required very early in the Moodle * setup process, before any of the main libraries are @@ -29,7 +27,7 @@ defined('MOODLE_INTERNAL') || die(); -/// Debug levels /// +// Debug levels // /** no warnings at all */ define('DEBUG_NONE', 0); /** E_ERROR | E_PARSE */ @@ -92,10 +90,30 @@ class object extends stdClass {}; * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class moodle_exception extends Exception { + + /** + * @var string The name of the string from error.php to print + */ public $errorcode; + + /** + * @var string The name of module + */ public $module; + + /** + * @var mixed Extra words and phrases that might be required in the error string + */ public $a; + + /** + * @var string The url where the user will be prompted to continue. If no url is provided the user will be directed to the site index page. + */ public $link; + + /** + * @var string Optional information to aid the debugging process + */ public $debuginfo; /** @@ -103,7 +121,7 @@ class moodle_exception extends Exception { * @param string $errorcode The name of the string from error.php to print * @param string $module name of module * @param string $link The url where the user will be prompted to continue. If no url is provided the user will be directed to the site index page. - * @param object $a Extra words and phrases that might be required in the error string + * @param mixed $a Extra words and phrases that might be required in the error string * @param string $debuginfo optional debugging information */ function __construct($errorcode, $module='', $link='', $a=NULL, $debuginfo=null) { @@ -137,6 +155,10 @@ class moodle_exception extends Exception { * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class require_login_exception extends moodle_exception { + /** + * Constructor + * @param string $debuginfo Information to aid the debugging process + */ function __construct($debuginfo) { parent::__construct('requireloginerror', 'error', '', NULL, $debuginfo); } @@ -153,6 +175,7 @@ class webservice_parameter_exception extends moodle_exception { * Constructor * @param string $errorcode The name of the string from webservice.php to print * @param string $a The name of the parameter + * @param string $debuginfo Optional information to aid debugging */ function __construct($errorcode=null, $a = '', $debuginfo = null) { parent::__construct($errorcode, 'webservice', '', $a, $debuginfo); @@ -168,6 +191,13 @@ class webservice_parameter_exception extends moodle_exception { * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class required_capability_exception extends moodle_exception { + /** + * Constructor + * @param context $context The context used for the capability check + * @param string $capability The required capability + * @param string $errormessage The error message to show the user + * @param string $stringfile + */ function __construct($context, $capability, $errormessage, $stringfile) { $capabilityname = get_capability_string($capability); if ($context->contextlevel == CONTEXT_MODULE and preg_match('/:view$/', $capability)) { @@ -1018,7 +1048,7 @@ function get_real_size($size = 0) { * Try to disable all output buffering and purge * all headers. * - * @private to be called only from lib/setup.php ! + * @access private to be called only from lib/setup.php ! * @return void */ function disable_output_buffering() { @@ -1219,6 +1249,11 @@ function make_cache_directory($directory, $exceptiononerror = true) { } +/** + * Initialises an Memcached instance + * @global memcached $MCACHE + * @return boolean Returns true if an mcached instance could be successfully initialised + */ function init_memcached() { global $CFG, $MCACHE; @@ -1231,6 +1266,11 @@ function init_memcached() { return false; } +/** + * Initialises an eAccelerator instance + * @global eaccelerator $MCACHE + * @return boolean Returns true if an eAccelerator instance could be successfully initialised + */ function init_eaccelerator() { global $CFG, $MCACHE; @@ -1330,8 +1370,8 @@ class bootstrap_renderer { /** * Constructor - to be used by core code only. - * @param $method - * @param $arguments + * @param string $method The method to call + * @param array $arguments Arguments to pass to the method being called * @return string */ public function __call($method, $arguments) { @@ -1476,7 +1516,7 @@ width: 80%; -moz-border-radius: 20px; padding: 15px"> /** * Early notification message * @static - * @param $message + * @param string $message * @param string $classes usually notifyproblem or notifysuccess * @return string */ @@ -1487,7 +1527,7 @@ width: 80%; -moz-border-radius: 20px; padding: 15px"> /** * Page should redirect message. * @static - * @param $encodedurl redirect url + * @param string $encodedurl redirect url * @return string */ public static function plain_redirect_message($encodedurl) { @@ -1499,9 +1539,9 @@ width: 80%; -moz-border-radius: 20px; padding: 15px"> /** * Early redirection page, used before full init of $PAGE global * @static - * @param $encodedurl redirect url - * @param $message redirect message - * @param $delay time in seconds + * @param string $encodedurl redirect url + * @param string $message redirect message + * @param int $delay time in seconds * @return string redirect page */ public static function early_redirect_message($encodedurl, $message, $delay) { @@ -1515,8 +1555,8 @@ width: 80%; -moz-border-radius: 20px; padding: 15px"> /** * Output basic html page. * @static - * @param $title page title - * @param $content page content + * @param string $title page title + * @param string $content page content * @param string $meta meta tag * @return string html page */