From 4615817d1c31673ba9b3c702f7da63619e0e8ce2 Mon Sep 17 00:00:00 2001 From: Jerome Mouneyrac Date: Wed, 18 Jan 2012 10:52:25 +0800 Subject: [PATCH] MDL-30986 external API, check and update DocBlock Conflicts: group/externallib.php --- course/externallib.php | 87 +++++++++++--- enrol/externallib.php | 143 ++++++++++++++++------ enrol/manual/externallib.php | 55 +++++++-- files/externallib.php | 112 +++++++++++++----- group/externallib.php | 223 ++++++++++++++++++++++++++--------- lib/externallib.php | 118 ++++++++++++++---- message/externallib.php | 55 ++++++--- notes/externallib.php | 54 +++++++-- user/externallib.php | 186 +++++++++++++++++++++++------ 9 files changed, 794 insertions(+), 239 deletions(-) diff --git a/course/externallib.php b/course/externallib.php index e6a86ea9e87cd..8fd2e4005b04b 100644 --- a/course/externallib.php +++ b/course/externallib.php @@ -1,5 +1,4 @@ . + /** * External course API * - * @package core - * @subpackage course - * @copyright 2010 Moodle Pty Ltd (http://moodle.com) + * @package core_course + * @category external + * @copyright 2009 Petr Skodak * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -29,13 +29,21 @@ require_once("$CFG->libdir/externallib.php"); /** - * Course functions + * Course external functions + * + * @package core_course + * @category external + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_course_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_course_contents_parameters() { return new external_function_parameters( @@ -52,9 +60,11 @@ public static function get_course_contents_parameters() { /** * Get course contents - * @param int $courseid - * @param array $options, not used yet, might be used in later version + * + * @param int $courseid course id + * @param array $options These options are not used yet, might be used in later version * @return array + * @since Moodle 2.2 */ public static function get_course_contents($courseid, $options) { global $CFG, $DB; @@ -183,7 +193,9 @@ public static function get_course_contents($courseid, $options) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function get_course_contents_returns() { return new external_multiple_structure( @@ -238,7 +250,9 @@ public static function get_course_contents_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_courses_parameters() { return new external_function_parameters( @@ -255,8 +269,10 @@ public static function get_courses_parameters() { /** * Get courses - * @param array $options + * + * @param array $options It contains an array (list of ids) * @return array + * @since Moodle 2.2 */ public static function get_courses($options) { global $CFG, $DB; @@ -336,7 +352,9 @@ public static function get_courses($options) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function get_courses_returns() { return new external_multiple_structure( @@ -402,7 +420,9 @@ public static function get_courses_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function create_courses_parameters() { $courseconfig = get_config('moodlecourse'); //needed for many default values @@ -471,8 +491,10 @@ public static function create_courses_parameters() { /** * Create courses + * * @param array $courses * @return array courses (id and shortname only) + * @since Moodle 2.2 */ public static function create_courses($courses) { global $CFG, $DB; @@ -556,7 +578,9 @@ public static function create_courses($courses) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function create_courses_returns() { return new external_multiple_structure( @@ -572,15 +596,26 @@ public static function create_courses_returns() { } /** - * Deprecated course functions - * @deprecated since Moodle 2.2 please use core_course_external instead + * Deprecated course external functions + * + * @package core_course + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_course_external */ class moodle_course_external extends external_api { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_course_external::get_courses_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_course_external::get_courses_parameters() */ public static function get_courses_parameters() { return core_course_external::get_courses_parameters(); @@ -588,9 +623,13 @@ public static function get_courses_parameters() { /** * Get courses + * * @param array $options - * @deprecated since Moodle 2.2 please use core_course_external::get_courses instead * @return array + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_course_external::get_courses() */ public static function get_courses($options) { return core_course_external::get_courses($options); @@ -598,8 +637,12 @@ public static function get_courses($options) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_course_external::get_courses_returns instead + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_course_external::get_courses_returns() */ public static function get_courses_returns() { return core_course_external::get_courses_returns(); @@ -607,8 +650,12 @@ public static function get_courses_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_course_external::create_courses_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_course_external::create_courses_parameters() */ public static function create_courses_parameters() { return core_course_external::create_courses_parameters(); @@ -616,9 +663,13 @@ public static function create_courses_parameters() { /** * Create courses - * @deprecated since Moodle 2.2 please use core_course_external::create_courses instead + * * @param array $courses * @return array courses (id and shortname only) + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_course_external::create_courses() */ public static function create_courses($courses) { return core_course_external::create_courses($courses); @@ -626,8 +677,12 @@ public static function create_courses($courses) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_course_external::create_courses_returns instead + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_course_external::create_courses_returns() */ public static function create_courses_returns() { return core_course_external::create_courses_returns(); diff --git a/enrol/externallib.php b/enrol/externallib.php index 71e0f69dfb767..57b6ac13efdce 100644 --- a/enrol/externallib.php +++ b/enrol/externallib.php @@ -1,5 +1,4 @@ . + /** * External course participation api. * * This api is mostly read only, the actual enrol and unenrol * support is in each enrol plugin. * - * @package core - * @subpackage enrol - * @copyright 2009 Moodle Pty Ltd (http://moodle.com) + * @package core_enrol + * @category external + * @copyright 2010 Jerome Mouneyrac * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -32,12 +32,19 @@ require_once("$CFG->libdir/externallib.php"); /** - * Enrol functions + * Enrol external functions + * + * @package core_enrol + * @category external + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_enrol_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters */ public static function get_users_courses_parameters() { @@ -50,7 +57,6 @@ public static function get_users_courses_parameters() { /** * Get list of courses user is enrolled in (only active enrolments are returned). - * * Please note the current user must be able to access the course, otherwise the course is not included. * * @param int $userid @@ -92,6 +98,7 @@ public static function get_users_courses($userid) { /** * Returns description of method result value + * * @return external_description */ public static function get_users_courses_returns() { @@ -111,6 +118,7 @@ public static function get_users_courses_returns() { /** * Returns description of method parameters + * * @return external_function_parameters */ public static function get_enrolled_users_parameters() { @@ -136,11 +144,12 @@ public static function get_enrolled_users_parameters() { /** * Get course participants details + * * @param int $courseid course id * @param array $options options { - * 'name' => option name - * 'value' => option value - * } + * 'name' => option name + * 'value' => option value + * } * @return array An array of users */ public static function get_enrolled_users($courseid, $options) { @@ -241,6 +250,7 @@ public static function get_enrolled_users($courseid, $options) { /** * Returns description of method result value + * * @return external_description */ public static function get_enrolled_users_returns() { @@ -322,12 +332,19 @@ public static function get_enrolled_users_returns() { } /** - * Role functions + * Role external functions + * + * @package core_role + * @category external + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_role_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters */ public static function assign_roles_parameters() { @@ -349,8 +366,7 @@ public static function assign_roles_parameters() { /** * Manual role assignments to users * - * @param array $assignment An array of manual role assignment - * @return null + * @param array $assignments An array of manual role assignment */ public static function assign_roles($assignments) { global $DB; @@ -382,7 +398,8 @@ public static function assign_roles($assignments) { /** * Returns description of method result value - * @return external_description + * + * @return null */ public static function assign_roles_returns() { return null; @@ -391,6 +408,7 @@ public static function assign_roles_returns() { /** * Returns description of method parameters + * * @return external_function_parameters */ public static function unassign_roles_parameters() { @@ -412,8 +430,7 @@ public static function unassign_roles_parameters() { /** * Unassign roles from users * - * @param array $unassignment An array of unassignment - * @return null + * @param array $unassignments An array of unassignment */ public static function unassign_roles($unassignments) { global $DB; @@ -444,6 +461,7 @@ public static function unassign_roles($unassignments) { /** * Returns description of method result value + * * @return null */ public static function unassign_roles_returns() { @@ -453,16 +471,28 @@ public static function unassign_roles_returns() { /** - * Deprecated enroll and role functions - * @deprecated since Moodle 2.2 please use core_enrol_external or core_role_external instead + * Deprecated enrol and role external functions + * + * @package core_enrol + * @copyright 2010 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external + * @see core_role_external */ class moodle_enrol_external extends external_api { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_parameters() instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_enrolled_users_parameters() */ public static function get_enrolled_users_parameters() { return new external_function_parameters( @@ -477,12 +507,16 @@ public static function get_enrolled_users_parameters() { /** * Get list of course participants. - * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users() instead + * * @param int $courseid * @param text $withcapability * @param int $groupid * @param bool $onlyactive * @return array of course participants + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_enrolled_users() */ public static function get_enrolled_users($courseid, $withcapability = null, $groupid = null, $onlyactive = false) { global $DB, $CFG, $USER; @@ -568,8 +602,12 @@ public static function get_enrolled_users($courseid, $withcapability = null, $gr /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_returns() instead + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_enrolled_users_returns() */ public static function get_enrolled_users_returns() { return new external_multiple_structure( @@ -590,8 +628,12 @@ public static function get_enrolled_users_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_enrol_external::get_users_courses_parameters() instead + * * @return external_function_parameters + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_users_courses_parameters() */ public static function get_users_courses_parameters() { return core_enrol_external::get_users_courses_parameters(); @@ -599,11 +641,14 @@ public static function get_users_courses_parameters() { /** * Get list of courses user is enrolled in (only active enrolments are returned). - * * Please note the current user must be able to access the course, otherwise the course is not included. - * @deprecated since Moodle 2.2 please use core_enrol_external::get_users_courses() instead + * * @param int $userid * @return array of courses + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see use core_enrol_external::get_users_courses() */ public static function get_users_courses($userid) { return core_enrol_external::get_users_courses($userid); @@ -611,8 +656,12 @@ public static function get_users_courses($userid) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_enrol_external::get_users_courses_returns() instead + * * @return external_description + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_users_courses_returns() */ public static function get_users_courses_returns() { return core_enrol_external::get_users_courses_returns(); @@ -621,8 +670,12 @@ public static function get_users_courses_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_role_external::assign_roles_parameters() instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_role_external::assign_roles_parameters() */ public static function role_assign_parameters() { return core_role_external::assign_roles_parameters(); @@ -630,9 +683,12 @@ public static function role_assign_parameters() { /** * Manual role assignments to users - * @deprecated since Moodle 2.2 please use core_role_external::assign_roles() instead - * @param array $assignment An array of manual role assignment - * @return null + * + * @param array $assignments An array of manual role assignment + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_role_external::assign_roles() */ public static function role_assign($assignments) { return core_role_external::assign_roles($assignments); @@ -640,8 +696,12 @@ public static function role_assign($assignments) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_role_external::assign_roles_returns() instead - * @return external_description + * + * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_role_external::assign_roles_returns() */ public static function role_assign_returns() { return core_role_external::assign_roles_returns(); @@ -650,8 +710,12 @@ public static function role_assign_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_role_external::unassign_roles_parameters() instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_role_external::unassign_roles_parameters() */ public static function role_unassign_parameters() { return core_role_external::unassign_roles_parameters(); @@ -659,9 +723,12 @@ public static function role_unassign_parameters() { /** * Unassign roles from users - * @deprecated since Moodle 2.2 please use core_role_external::unassign_roles() instead - * @param array $unassignment An array of unassignment - * @return null + * + * @param array $unassignments An array of unassignment + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_role_external::unassign_roles() */ public static function role_unassign($unassignments) { return core_role_external::unassign_roles($unassignments); @@ -669,8 +736,12 @@ public static function role_unassign($unassignments) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_role_external::unassign_roles_returns() instead - * @return external_description + * + * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_role_external::unassign_roles_returns() */ public static function role_unassign_returns() { return core_role_external::unassign_roles_returns(); diff --git a/enrol/manual/externallib.php b/enrol/manual/externallib.php index f2daf62773de7..44d90acc519b4 100644 --- a/enrol/manual/externallib.php +++ b/enrol/manual/externallib.php @@ -14,29 +14,39 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . + /** * External course participation api. * * This api is mostly read only, the actual enrol and unenrol * support is in each enrol plugin. * - * @package enrol - * @subpackage manual - * @copyright 2011 Moodle Pty Ltd (http://moodle.com) + * @package enrol_manual + * @category external + * @copyright 2011 Jerome Mouneyrac * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ + defined('MOODLE_INTERNAL') || die(); require_once("$CFG->libdir/externallib.php"); /** - * Manual enrolment functions + * Manual enrolment external functions + * + * @package enrol_manual + * @category external + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class enrol_manual_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function enrol_users_parameters() { return new external_function_parameters( @@ -59,9 +69,10 @@ public static function enrol_users_parameters() { /** * Enrolment of users + * * Function throw an exception at the first error encountered. * @param array $enrolments An array of user enrolment - * @return null + * @since Moodle 2.2 */ public static function enrol_users($enrolments) { global $DB, $CFG; @@ -137,7 +148,9 @@ public static function enrol_users($enrolments) { /** * Returns description of method result value + * * @return null + * @since Moodle 2.2 */ public static function enrol_users_returns() { return null; @@ -146,15 +159,26 @@ public static function enrol_users_returns() { } /** - * Deprecated manual enrolment functions - * @deprecated since Moodle 2.2 please use enrol_manual_external instead + * Deprecated manual enrolment external functions + * + * @package enrol_manual + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see enrol_manual_external */ class moodle_enrol_manual_external extends external_api { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use enrol_manual_external::enrol_users_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see enrol_manual_external::enrol_users_parameters() */ public static function manual_enrol_users_parameters() { return enrol_manual_external::enrol_users_parameters(); @@ -163,9 +187,12 @@ public static function manual_enrol_users_parameters() { /** * Enrolment of users * Function throw an exception at the first error encountered. - * @deprecated since Moodle 2.2 please use enrol_manual_external::enrol_users instead + * * @param array $enrolments An array of user enrolment - * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see enrol_manual_external::enrol_users() */ public static function manual_enrol_users($enrolments) { return enrol_manual_external::enrol_users($enrolments); @@ -173,8 +200,12 @@ public static function manual_enrol_users($enrolments) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use enrol_manual_external::enrol_users_returns instead - * @return external_description + * + * @return nul + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see enrol_manual_external::enrol_users_returns() */ public static function manual_enrol_users_returns() { return enrol_manual_external::enrol_users_returns(); diff --git a/files/externallib.php b/files/externallib.php index 530f18d4c3205..ec167245352e7 100644 --- a/files/externallib.php +++ b/files/externallib.php @@ -1,5 +1,4 @@ . + /** * External files API * - * @package moodlecore - * @subpackage webservice - * @copyright 2010 Dongsheng Cai + * @package core_files + * @category external + * @copyright 2010 Dongsheng Cai * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -28,13 +28,21 @@ require_once("$CFG->libdir/filelib.php"); /** - * Files functions + * Files external functions + * + * @package core_files + * @category external + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_files_external extends external_api { /** * Returns description of get_files parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_files_parameters() { return new external_function_parameters( @@ -51,13 +59,15 @@ public static function get_files_parameters() { /** * Return moodle files listing - * @param int $contextid - * @param int $component - * @param int $filearea - * @param int $itemid - * @param string $filepath - * @param string $filename + * + * @param int $contextid context id + * @param int $component component + * @param int $filearea file aera + * @param int $itemid item id + * @param string $filepath file path + * @param string $filename file name * @return array + * @since Moodle 2.2 */ public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) { global $CFG, $USER, $OUTPUT; @@ -136,7 +146,9 @@ public static function get_files($contextid, $component, $filearea, $itemid, $fi /** * Returns description of get_files returns - * @return external_multiple_structure + * + * @return external_single_structure + * @since Moodle 2.2 */ public static function get_files_returns() { return new external_single_structure( @@ -173,7 +185,9 @@ public static function get_files_returns() { /** * Returns description of upload parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function upload_parameters() { return new external_function_parameters( @@ -192,14 +206,15 @@ public static function upload_parameters() { /** * Uploading a file to moodle * - * @param int $contextid - * @param string $component - * @param string $filearea - * @param int $itemid - * @param string $filepath - * @param string $filename - * @param string $filecontent + * @param int $contextid context id + * @param string $component component + * @param string $filearea file aera + * @param int $itemid item id + * @param string $filepath file path + * @param string $filename file name + * @param string $filecontent file content * @return array + * @since Moodle 2.2 */ public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) { global $USER, $CFG; @@ -235,7 +250,7 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep } if (isset($fileinfo['itemid'])) { - // TODO: in user private area, itemid is always 0 + // TODO MDL-31116 in user private area, itemid is always 0 $itemid = 0; } else { throw new coding_exception('itemid cannot be empty'); @@ -250,7 +265,7 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) { throw new coding_exception('File can be uploaded to user private area only'); } else { - // TODO: hard-coded to use user_private area + // TODO MDL-31116 hard-coded to use user_private area $component = 'user'; $filearea = 'private'; } @@ -283,7 +298,9 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep /** * Returns description of upload returns - * @return external_multiple_structure + * + * @return external_single_structure + * @since Moodle 2.2 */ public static function upload_returns() { return new external_single_structure( @@ -301,15 +318,26 @@ public static function upload_returns() { } /** - * Deprecated files functions - * @deprecated since Moodle 2.2 please use core_files_external instead + * Deprecated files external functions + * + * @package core_files + * @copyright 2010 Dongsheng Cai + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_files_external */ class moodle_file_external extends external_api { /** * Returns description of get_files parameters - * @deprecated since Moodle 2.2 please use core_files_external::get_files_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_files_external::get_files_parameters() */ public static function get_files_parameters() { return core_files_external::get_files_parameters(); @@ -317,7 +345,7 @@ public static function get_files_parameters() { /** * Return moodle files listing - * @deprecated since Moodle 2.2 please use core_files_external::get_files instead + * * @param int $contextid * @param int $component * @param int $filearea @@ -325,6 +353,10 @@ public static function get_files_parameters() { * @param string $filepath * @param string $filename * @return array + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_files_external::get_files() */ public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) { return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename); @@ -332,8 +364,12 @@ public static function get_files($contextid, $component, $filearea, $itemid, $fi /** * Returns description of get_files returns - * @deprecated since Moodle 2.2 please use core_files_external::get_files_returns instead - * @return external_multiple_structure + * + * @return external_single_structure + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_files_external::get_files_returns() */ public static function get_files_returns() { return core_files_external::get_files_returns(); @@ -341,8 +377,12 @@ public static function get_files_returns() { /** * Returns description of upload parameters - * @deprecated since Moodle 2.2 please use core_files_external::upload_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_files_external::upload_parameters() */ public static function upload_parameters() { return core_files_external::upload_parameters(); @@ -350,7 +390,7 @@ public static function upload_parameters() { /** * Uploading a file to moodle - * @deprecated since Moodle 2.2 please use core_files_external::upload instead + * * @param int $contextid * @param string $component * @param string $filearea @@ -359,6 +399,10 @@ public static function upload_parameters() { * @param string $filename * @param string $filecontent * @return array + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_files_external::upload() */ public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) { return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent); @@ -366,8 +410,12 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep /** * Returns description of upload returns - * @deprecated since Moodle 2.2 please use core_files_external::upload_returns instead - * @return external_multiple_structure + * + * @return external_single_structure + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_files_external::upload_returns() */ public static function upload_returns() { return core_files_external::upload_returns(); diff --git a/group/externallib.php b/group/externallib.php index ceadcb7fcdbe2..128ad9e4ba5ec 100644 --- a/group/externallib.php +++ b/group/externallib.php @@ -14,28 +14,34 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . + /** * External groups API * * @package core_group - * @copyright 2009 Moodle Pty Ltd (http://moodle.com) + * @category external + * @copyright 2009 Petr Skodak * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once("$CFG->libdir/externallib.php"); /** - * Group functions + * Group external functions * * @package core_group - * @copyright 2009 Moodle Pty Ltd (http://moodle.com) + * @category external + * @copyright 2011 Jerome Mouneyrac * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_group_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function create_groups_parameters() { return new external_function_parameters( @@ -56,8 +62,10 @@ public static function create_groups_parameters() { /** * Create groups + * * @param array $groups array of group description arrays (with keys groupname and courseid) * @return array of newly created groups + * @since Moodle 2.2 */ public static function create_groups($groups) { global $CFG, $DB; @@ -104,7 +112,9 @@ public static function create_groups($groups) { /** * Returns description of method result value - * @return external_multiple_structure + * + * @return external_description + * @since Moodle 2.2 */ public static function create_groups_returns() { return new external_multiple_structure( @@ -122,7 +132,9 @@ public static function create_groups_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_groups_parameters() { return new external_function_parameters( @@ -135,8 +147,10 @@ public static function get_groups_parameters() { /** * Get groups definition specified by ids + * * @param array $groupids arrays of group ids * @return array of group objects (id, courseid, name, enrolmentkey) + * @since Moodle 2.2 */ public static function get_groups($groupids) { $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids)); @@ -167,7 +181,9 @@ public static function get_groups($groupids) { /** * Returns description of method result value - * @return external_multiple_structure + * + * @return external_description + * @since Moodle 2.2 */ public static function get_groups_returns() { return new external_multiple_structure( @@ -185,7 +201,9 @@ public static function get_groups_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_course_groups_parameters() { return new external_function_parameters( @@ -197,8 +215,10 @@ public static function get_course_groups_parameters() { /** * Get all groups in the specified course + * * @param int $courseid id of course * @return array of group objects (id, courseid, name, enrolmentkey) + * @since Moodle 2.2 */ public static function get_course_groups($courseid) { $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid)); @@ -228,7 +248,9 @@ public static function get_course_groups($courseid) { /** * Returns description of method result value - * @return external_multiple_structure + * + * @return external_description + * @since Moodle 2.2 */ public static function get_course_groups_returns() { return new external_multiple_structure( @@ -246,7 +268,9 @@ public static function get_course_groups_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function delete_groups_parameters() { return new external_function_parameters( @@ -258,8 +282,9 @@ public static function delete_groups_parameters() { /** * Delete groups + * * @param array $groupids array of group ids - * @return void + * @since Moodle 2.2 */ public static function delete_groups($groupids) { global $CFG, $DB; @@ -298,7 +323,9 @@ public static function delete_groups($groupids) { /** * Returns description of method result value - * @return external_description + * + * @return null + * @since Moodle 2.2 */ public static function delete_groups_returns() { return null; @@ -307,7 +334,9 @@ public static function delete_groups_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_group_members_parameters() { return new external_function_parameters( @@ -319,8 +348,10 @@ public static function get_group_members_parameters() { /** * Return all members for a group + * * @param array $groupids array of group ids * @return array with group id keys containing arrays of user ids + * @since Moodle 2.2 */ public static function get_group_members($groupids) { $members = array(); @@ -353,7 +384,9 @@ public static function get_group_members($groupids) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function get_group_members_returns() { return new external_multiple_structure( @@ -369,7 +402,9 @@ public static function get_group_members_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function add_group_members_parameters() { return new external_function_parameters( @@ -388,7 +423,9 @@ public static function add_group_members_parameters() { /** * Add group members + * * @param array $members of arrays with keys userid, groupid + * @since Moodle 2.2 */ public static function add_group_members($members) { global $CFG, $DB; @@ -432,7 +469,9 @@ public static function add_group_members($members) { /** * Returns description of method result value + * * @return null + * @since Moodle 2.2 */ public static function add_group_members_returns() { return null; @@ -441,7 +480,9 @@ public static function add_group_members_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function delete_group_members_parameters() { return new external_function_parameters( @@ -460,7 +501,9 @@ public static function delete_group_members_parameters() { /** * Delete group members + * * @param array $members of arrays with keys userid, groupid + * @since Moodle 2.2 */ public static function delete_group_members($members) { global $CFG, $DB; @@ -499,7 +542,9 @@ public static function delete_group_members($members) { /** * Returns description of method result value + * * @return null + * @since Moodle 2.2 */ public static function delete_group_members_returns() { return null; @@ -508,17 +553,26 @@ public static function delete_group_members_returns() { } /** - * Deprecated group functions - * @deprecated since Moodle 2.2 please do not call this class any more. - * @see core_group_external() + * Deprecated group external functions + * + * @package core_group + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external */ class moodle_group_external extends external_api { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::create_groups_parameters() + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::create_groups_parameters() */ public static function create_groups_parameters() { return core_group_external::create_groups_parameters(); @@ -526,10 +580,13 @@ public static function create_groups_parameters() { /** * Create groups - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::create_groups() + * * @param array $groups array of group description arrays (with keys groupname and courseid) * @return array of newly created groups + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see use core_group_external::create_groups() */ public static function create_groups($groups) { return core_group_external::create_groups($groups); @@ -537,9 +594,12 @@ public static function create_groups($groups) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::create_groups_returns() + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::create_groups_returns() */ public static function create_groups_returns() { return core_group_external::create_groups_returns(); @@ -547,9 +607,12 @@ public static function create_groups_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_groups_parameters() + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_groups_parameters() */ public static function get_groups_parameters() { return core_group_external::get_groups_parameters(); @@ -557,10 +620,13 @@ public static function get_groups_parameters() { /** * Get groups definition specified by ids - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_groups() + * * @param array $groupids arrays of group ids * @return array of group objects (id, courseid, name, enrolmentkey) + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_groups() */ public static function get_groups($groupids) { return core_group_external::get_groups($groupids); @@ -568,9 +634,12 @@ public static function get_groups($groupids) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_groups_returns() + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_groups_returns() */ public static function get_groups_returns() { return core_group_external::get_groups_returns(); @@ -578,9 +647,12 @@ public static function get_groups_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_course_groups_parameters() + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_course_groups_parameters() */ public static function get_course_groups_parameters() { return core_group_external::get_course_groups_parameters(); @@ -588,10 +660,13 @@ public static function get_course_groups_parameters() { /** * Get all groups in the specified course - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_course_groups() + * * @param int $courseid id of course * @return array of group objects (id, courseid, name, enrolmentkey) + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_course_groups() */ public static function get_course_groups($courseid) { return core_group_external::get_course_groups($courseid); @@ -599,9 +674,12 @@ public static function get_course_groups($courseid) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_course_groups_returns() + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_course_groups_returns() */ public static function get_course_groups_returns() { return core_group_external::get_course_groups_returns(); @@ -609,9 +687,12 @@ public static function get_course_groups_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::delete_group_members_parameters() + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::delete_group_members_parameters() */ public static function delete_groups_parameters() { return core_group_external::delete_group_members_parameters(); @@ -619,10 +700,12 @@ public static function delete_groups_parameters() { /** * Delete groups - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::delete_groups() + * * @param array $groupids array of group ids - * @return void + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::delete_groups() */ public static function delete_groups($groupids) { return core_group_external::delete_groups($groupids); @@ -630,9 +713,12 @@ public static function delete_groups($groupids) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please do not call this function any more. + * + * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. * @see core_group_external::delete_group_members_returns() - * @return external_description */ public static function delete_groups_returns() { return core_group_external::delete_group_members_returns(); @@ -641,9 +727,12 @@ public static function delete_groups_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_group_members_parameters() + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_group_members_parameters() */ public static function get_groupmembers_parameters() { return core_group_external::get_group_members_parameters(); @@ -651,10 +740,13 @@ public static function get_groupmembers_parameters() { /** * Return all members for a group - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_group_members() + * * @param array $groupids array of group ids * @return array with group id keys containing arrays of user ids + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_group_members() */ public static function get_groupmembers($groupids) { return core_group_external::get_group_members($groupids); @@ -662,9 +754,12 @@ public static function get_groupmembers($groupids) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::get_group_members_returns() + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::get_group_members_returns() */ public static function get_groupmembers_returns() { return core_group_external::get_group_members_returns(); @@ -673,9 +768,12 @@ public static function get_groupmembers_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::add_group_members_parameters() + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::add_group_members_parameters() */ public static function add_groupmembers_parameters() { return core_group_external::add_group_members_parameters(); @@ -683,10 +781,12 @@ public static function add_groupmembers_parameters() { /** * Add group members - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::add_group_members() + * * @param array $members of arrays with keys userid, groupid - * @return void + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see use core_group_external::add_group_members() */ public static function add_groupmembers($members) { return core_group_external::add_group_members($members); @@ -694,9 +794,12 @@ public static function add_groupmembers($members) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::add_group_members_returns() + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::add_group_members_returns() */ public static function add_groupmembers_returns() { return core_group_external::add_group_members_returns(); @@ -705,9 +808,12 @@ public static function add_groupmembers_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::delete_group_members_parameters() + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::delete_group_members_parameters() */ public static function delete_groupmembers_parameters() { return core_group_external::delete_group_members_parameters(); @@ -715,10 +821,12 @@ public static function delete_groupmembers_parameters() { /** * Delete group members - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::delete_group_members() + * * @param array $members of arrays with keys userid, groupid - * @return void + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::delete_group_members() */ public static function delete_groupmembers($members) { return core_group_external::delete_group_members($members); @@ -726,9 +834,12 @@ public static function delete_groupmembers($members) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please do not call this function any more. - * @see core_group_external::delete_group_members_returns() + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_group_external::delete_group_members_returns() */ public static function delete_groupmembers_returns() { return core_group_external::delete_group_members_returns(); diff --git a/lib/externallib.php b/lib/externallib.php index 2cb1118d9605d..3eb1f1fce7dd7 100644 --- a/lib/externallib.php +++ b/lib/externallib.php @@ -1,5 +1,4 @@ . + /** * Support for external API * - * @package core - * @subpackage webservice - * @copyright 2009 Moodle Pty Ltd (http://moodle.com) + * @package core_webservice + * @copyright 2009 Petr Skodak * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -28,10 +27,12 @@ /** * Returns detailed function information + * * @param string|object $function name of external function or record from external_function * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found; * MUST_EXIST means throw exception if no record or multiple records found - * @return object description or false if not found or exception thrown + * @return stdClass description or false if not found or exception thrown + * @since Moodle 2.0 */ function external_function_info($function, $strictness=MUST_EXIST) { global $DB, $CFG; @@ -77,7 +78,7 @@ function external_function_info($function, $strictness=MUST_EXIST) { } //now get the function description - //TODO: use localised lang pack descriptions, it would be nice to have + //TODO MDL-31115 use localised lang pack descriptions, it would be nice to have // easy to understand descriptions in admin UI, // on the other hand this is still a bit in a flux and we need to find some new naming // conventions for these descriptions in lang packs @@ -98,12 +99,18 @@ function external_function_info($function, $strictness=MUST_EXIST) { } /** - * Exception indicating user is not allowed to use external function in - * the current context. + * Exception indicating user is not allowed to use external function in the current context. + * + * @package core_webservice + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 */ class restricted_context_exception extends moodle_exception { /** * Constructor + * + * @since Moodle 2.0 */ function __construct() { parent::__construct('restrictedcontextexception', 'error'); @@ -112,14 +119,22 @@ function __construct() { /** * Base class for external api methods. + * + * @package core_webservice + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 */ class external_api { + + /** @var stdClass context where the function calls will be restricted */ private static $contextrestriction; /** * Set context restriction for all following subsequent function calls. - * @param stdClass $contex - * @return void + * + * @param stdClass $context the context restriction + * @since Moodle 2.0 */ public static function set_context_restriction($context) { self::$contextrestriction = $context; @@ -130,7 +145,7 @@ public static function set_context_restriction($context) { * that takes a longer time to finish! * * @param int $seconds max expected time the next operation needs - * @return void + * @since Moodle 2.0 */ public static function set_timeout($seconds=360) { $seconds = ($seconds < 300) ? 300 : $seconds; @@ -142,9 +157,11 @@ public static function set_timeout($seconds=360) { * invalid_parameter_exception is thrown. * This is a simple recursive method which is intended to be called from * each implementation method of external API. + * * @param external_description $description description of parameters * @param mixed $params the actual parameters * @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found + * @since Moodle 2.0 */ public static function validate_parameters(external_description $description, $params) { if ($description instanceof external_value) { @@ -220,9 +237,12 @@ public static function validate_parameters(external_description $description, $p * If a response attribute is incorrect, invalid_response_exception is thrown. * Note: this function is similar to validate parameters, however it is distinct because * parameters validation must be distinct from cleaning return values. + * * @param external_description $description description of the return values * @param mixed $response the actual response * @return mixed response with added defaults for optional items, invalid_response_exception thrown if any problem found + * @author 2010 Jerome Mouneyrac + * @since Moodle 2.0 */ public static function clean_returnvalue(external_description $description, $response) { if ($description instanceof external_value) { @@ -297,8 +317,9 @@ public static function clean_returnvalue(external_description $description, $res /** * Makes sure user may execute functions in this context. - * @param object $context - * @return void + * + * @param stdClass $context + * @since Moodle 2.0 */ protected static function validate_context($context) { global $CFG; @@ -333,20 +354,29 @@ protected static function validate_context($context) { /** * Common ancestor of all parameter description classes + * + * @package core_webservice + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 */ abstract class external_description { - /** @var string $description description of element */ + /** @var string Description of element */ public $desc; - /** @var bool $required element value required, null not allowed */ + + /** @var bool Element value required, null not allowed */ public $required; - /** @var mixed $default default value */ + + /** @var mixed Default value */ public $default; /** * Contructor + * * @param string $desc * @param bool $required * @param mixed $default + * @since Moodle 2.0 */ public function __construct($desc, $required, $default) { $this->desc = $desc; @@ -356,21 +386,30 @@ public function __construct($desc, $required, $default) { } /** - * Scalar alue description class + * Scalar value description class + * + * @package core_webservice + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 */ class external_value extends external_description { - /** @var mixed $type value type PARAM_XX */ + + /** @var mixed Value type PARAM_XX */ public $type; - /** @var bool $allownull allow null values */ + + /** @var bool Allow null values */ public $allownull; /** * Constructor + * * @param mixed $type * @param string $desc * @param bool $required * @param mixed $default * @param bool $allownull + * @since Moodle 2.0 */ public function __construct($type, $desc='', $required=VALUE_REQUIRED, $default=null, $allownull=NULL_ALLOWED) { @@ -382,17 +421,25 @@ public function __construct($type, $desc='', $required=VALUE_REQUIRED, /** * Associative array description class + * + * @package core_webservice + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 */ class external_single_structure extends external_description { - /** @var array $keys description of array keys key=>external_description */ + + /** @var array Description of array keys key=>external_description */ public $keys; /** * Constructor + * * @param array $keys * @param string $desc * @param bool $required * @param array $default + * @since Moodle 2.0 */ public function __construct(array $keys, $desc='', $required=VALUE_REQUIRED, $default=null) { @@ -403,17 +450,25 @@ public function __construct(array $keys, $desc='', /** * Bulk array description class. + * + * @package core_webservice + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 */ class external_multiple_structure extends external_description { - /** @var external_description $content */ + + /** @var external_description content */ public $content; /** * Constructor + * * @param external_description $content * @param string $desc * @param bool $required * @param array $default + * @since Moodle 2.0 */ public function __construct(external_description $content, $desc='', $required=VALUE_REQUIRED, $default=null) { @@ -424,12 +479,28 @@ public function __construct(external_description $content, $desc='', /** * Description of top level - PHP function parameters. - * @author skodak * + * @package core_webservice + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 */ class external_function_parameters extends external_single_structure { } +/** + * Generate a token + * + * @param string $tokentype EXTERNAL_TOKEN_EMBEDDED|EXTERNAL_TOKEN_PERMANENT + * @param stdClass|int $serviceorid service linked to the token + * @param int $userid user linked to the token + * @param stdClass|int $contextorid + * @param int $validuntil date when the token expired + * @param string $iprestriction allowed ip - if 0 or empty then all ips are allowed + * @return string generated token + * @author 2010 Jamie Pratt + * @since Moodle 2.0 + */ function external_generate_token($tokentype, $serviceorid, $userid, $contextorid, $validuntil=0, $iprestriction=''){ global $DB, $USER; // make sure the token doesn't exist (even if it should be almost impossible with the random generation) @@ -474,14 +545,17 @@ function external_generate_token($tokentype, $serviceorid, $userid, $contextorid $DB->insert_record('external_tokens', $newtoken); return $newtoken->token; } + /** * Create and return a session linked token. Token to be used for html embedded client apps that want to communicate * with the Moodle server through web services. The token is linked to the current session for the current page request. * It is expected this will be called in the script generating the html page that is embedding the client app and that the * returned token will be somehow passed into the client app being embedded in the page. + * * @param string $servicename name of the web service. Service name as defined in db/services.php * @param int $context context within which the web service can operate. * @return int returns token id. + * @since Moodle 2.0 */ function external_create_service_token($servicename, $context){ global $USER, $DB; diff --git a/message/externallib.php b/message/externallib.php index 76e8d9f1690eb..f39d51798216b 100644 --- a/message/externallib.php +++ b/message/externallib.php @@ -14,27 +14,34 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . + /** * External message API * * @package core_message - * @copyright 2011 Moodle Pty Ltd (http://moodle.com) + * @category external + * @copyright 2011 Jerome Mouneyrac * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ + require_once("$CFG->libdir/externallib.php"); /** - * Message functions + * Message external functions * * @package core_message - * @copyright 2011 Moodle Pty Ltd (http://moodle.com) + * @category external + * @copyright 2011 Jerome Mouneyrac * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_message_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function send_instant_messages_parameters() { return new external_function_parameters( @@ -55,8 +62,9 @@ public static function send_instant_messages_parameters() { /** * Send private messages from the current USER to other users * - * @param array $messages An array of message to send - * @return boolean + * @param array $messages An array of message to send. + * @return array + * @since Moodle 2.2 */ public static function send_instant_messages($messages = array()) { global $CFG, $USER, $DB; @@ -123,7 +131,7 @@ public static function send_instant_messages($messages = array()) { } // Check if the user is a contact - //TODO: performance improvement - edit the function so we can pass an array instead userid + //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead userid $blocknoncontacts = get_user_preferences('message_blocknoncontacts', NULL, $message['touserid']); // message_blocknoncontacts option is on and current user is not in contact list if ($success && empty($contactlist[$message['touserid']]) && !empty($blocknoncontacts)) { @@ -134,7 +142,7 @@ public static function send_instant_messages($messages = array()) { //now we can send the message (at least try) if ($success) { - //TODO: performance improvement - edit the function so we can pass an array instead one touser object + //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead one touser object $success = message_post_message($USER, $tousers[$message['touserid']], $text, FORMAT_MOODLE); } @@ -157,7 +165,9 @@ public static function send_instant_messages($messages = array()) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function send_instant_messages_returns() { return new external_multiple_structure( @@ -174,19 +184,26 @@ public static function send_instant_messages_returns() { } /** - * Deprecated message functions + * Deprecated message external functions * - * @deprecated since Moodle 2.2 please use core_message_external instead - * @copyright 2011 Moodle Pty Ltd (http://moodle.com) - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package core_message + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_notes_external */ class moodle_message_external extends external_api { /** * Returns description of method parameters * - * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages_parameters instead * @return external_function_parameters + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_message_external::send_instant_messages_parameters() */ public static function send_instantmessages_parameters() { return core_message_external::send_instant_messages_parameters(); @@ -195,9 +212,12 @@ public static function send_instantmessages_parameters() { /** * Send private messages from the current USER to other users * - * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages instead - * @param array $messages An array of message to send. - * @return boolean + * @param array $messages An array of message to send. + * @return array + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_message_external::send_instant_messages() */ public static function send_instantmessages($messages = array()) { return core_message_external::send_instant_messages($messages); @@ -206,8 +226,11 @@ public static function send_instantmessages($messages = array()) { /** * Returns description of method result value * - * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages_returns instead * @return external_description + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_message_external::send_instant_messages_returns() */ public static function send_instantmessages_returns() { return core_message_external::send_instant_messages_returns(); diff --git a/notes/externallib.php b/notes/externallib.php index 9b704832f044f..f9a1bf912d6aa 100644 --- a/notes/externallib.php +++ b/notes/externallib.php @@ -1,5 +1,4 @@ . + /** * External notes API * - * @package moodlecore - * @subpackage notes - * @copyright 2011 Moodle Pty Ltd (http://moodle.com) + * @package core_notes + * @category external + * @copyright 2011 Jerome Mouneyrac * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ + require_once("$CFG->libdir/externallib.php"); /** - * Notes functions + * Notes external functions + * + * @package core_notes + * @category external + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_notes_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function create_notes_parameters() { return new external_function_parameters( @@ -57,8 +66,10 @@ public static function create_notes_parameters() { * Create notes about some users * Note: code should be matching the /notes/edit.php checks * and the /user/addnote.php checks. (they are similar cheks) + * * @param array $notes An array of notes to create. * @return array (success infos and fail infos) + * @since Moodle 2.2 */ public static function create_notes($notes = array()) { global $CFG, $DB; @@ -148,7 +159,7 @@ public static function create_notes($notes = array()) { break; } - //TODO: performance improvement - if possible create a bulk functions for saving multiple notes at once + //TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once if (note_save($dbnote)) { //note_save attribut an id in case of success add_to_log($dbnote->courseid, 'notes', 'add', 'index.php?course='.$dbnote->courseid.'&user='.$dbnote->userid @@ -170,7 +181,9 @@ public static function create_notes($notes = array()) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function create_notes_returns() { return new external_multiple_structure( @@ -187,15 +200,26 @@ public static function create_notes_returns() { } /** - * Deprecated notes functions - * @deprecated since Moodle 2.2 please use core_notes_external instead + * Deprecated notes external functions + * + * @package core_notes + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_notes_external */ class moodle_notes_external extends external_api { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_notes_external::create_notes_parameters instead + * * @return external_function_parameters + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_notes_external::create_notes_parameters() */ public static function create_notes_parameters() { return core_notes_external::create_notes_parameters(); @@ -205,9 +229,13 @@ public static function create_notes_parameters() { * Create notes about some users * Note: code should be matching the /notes/edit.php checks * and the /user/addnote.php checks. (they are similar cheks) - * @deprecated since Moodle 2.2 please use core_notes_external::create_notes instead + * * @param array $notes An array of notes to create. * @return array (success infos and fail infos) + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_notes_external::create_notes() */ public static function create_notes($notes = array()) { return core_notes_external::create_notes($notes); @@ -215,8 +243,12 @@ public static function create_notes($notes = array()) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_notes_external::create_notes_returns instead + * * @return external_description + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_notes_external::create_notes_returns() */ public static function create_notes_returns() { return core_notes_external::create_notes_returns(); diff --git a/user/externallib.php b/user/externallib.php index 0fba109facf75..a309ec27855cc 100644 --- a/user/externallib.php +++ b/user/externallib.php @@ -1,5 +1,4 @@ . + /** * External user API * - * @package moodlecore - * @subpackage webservice - * @copyright 2009 Moodle Pty Ltd (http://moodle.com) + * @package core_user + * @category external + * @copyright 2009 Petr Skodak * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once("$CFG->libdir/externallib.php"); /** - * User functions + * User external functions + * + * @package core_user + * @category external + * @copyright 2011 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.2 */ class core_user_external extends external_api { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function create_users_parameters() { global $CFG; @@ -81,16 +89,15 @@ public static function create_users_parameters() { /** * Create one or more users * - * @param array $users An array of users to create. + * @param array $users An array of users to create. * @return array An array of arrays + * @since Moodle 2.2 */ public static function create_users($users) { global $CFG, $DB; require_once($CFG->dirroot."/lib/weblib.php"); require_once($CFG->dirroot."/user/lib.php"); require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function - //TODO: move the functions somewhere else as - //they are "user" related // Ensure the current user is allowed to run this function $context = get_context_instance(CONTEXT_SYSTEM); @@ -177,7 +184,9 @@ public static function create_users($users) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function create_users_returns() { return new external_multiple_structure( @@ -193,7 +202,9 @@ public static function create_users_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function delete_users_parameters() { return new external_function_parameters( @@ -205,8 +216,10 @@ public static function delete_users_parameters() { /** * Delete users + * * @param array $userids * @return null + * @since Moodle 2.2 */ public static function delete_users($userids) { global $CFG, $DB, $USER; @@ -240,7 +253,9 @@ public static function delete_users($userids) { /** * Returns description of method result value - * @return external_description + * + * @return null + * @since Moodle 2.2 */ public static function delete_users_returns() { return null; @@ -249,7 +264,9 @@ public static function delete_users_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function update_users_parameters() { global $CFG; @@ -296,15 +313,15 @@ public static function update_users_parameters() { /** * Update users + * * @param array $users * @return null + * @since Moodle 2.2 */ public static function update_users($users) { global $CFG, $DB; require_once($CFG->dirroot."/user/lib.php"); require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function - //TODO: move the functions somewhere else as - //they are "user" related // Ensure the current user is allowed to run this function $context = get_context_instance(CONTEXT_SYSTEM); @@ -343,7 +360,9 @@ public static function update_users($users) { /** * Returns description of method result value - * @return external_description + * + * @return null + * @since Moodle 2.2 */ public static function update_users_returns() { return null; @@ -351,7 +370,9 @@ public static function update_users_returns() { /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_users_by_id_parameters() { return new external_function_parameters( @@ -366,8 +387,10 @@ public static function get_users_by_id_parameters() { * - This function is matching the permissions of /user/profil.php * - It is also matching some permissions from /user/editadvanced.php for the following fields: * auth, confirmed, idnumber, lang, theme, timezone, mailformat + * * @param array $userids array of user ids * @return array An array of arrays describing users + * @since Moodle 2.2 */ public static function get_users_by_id($userids) { global $CFG, $USER, $DB; @@ -415,7 +438,9 @@ public static function get_users_by_id($userids) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function get_users_by_id_returns() { return new external_multiple_structure( @@ -484,7 +509,9 @@ public static function get_users_by_id_returns() { } /** * Returns description of method parameters + * * @return external_function_parameters + * @since Moodle 2.2 */ public static function get_course_user_profiles_parameters() { return new external_function_parameters( @@ -503,8 +530,10 @@ public static function get_course_user_profiles_parameters() { /** * Get course participant's details + * * @param array $userlist array of user ids and according course ids * @return array An array of arrays describing course participants + * @since Moodle 2.2 */ public static function get_course_user_profiles($userlist) { global $CFG, $USER, $DB; @@ -561,7 +590,9 @@ public static function get_course_user_profiles($userlist) { /** * Returns description of method result value + * * @return external_description + * @since Moodle 2.2 */ public static function get_course_user_profiles_returns() { return new external_multiple_structure( @@ -640,16 +671,27 @@ public static function get_course_user_profiles_returns() { } } -/** - * Deprecated user functions - * @deprecated since Moodle 2.2 please use core_user_external instead + /** + * Deprecated user external functions + * + * @package core_user + * @copyright 2009 Petr Skodak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external */ class moodle_user_external extends external_api { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_user_external::create_users_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::create_users_parameters() */ public static function create_users_parameters() { return core_user_external::create_users_parameters(); @@ -657,9 +699,13 @@ public static function create_users_parameters() { /** * Create one or more users - * @deprecated since Moodle 2.2 please use core_user_external::create_users instead + * * @param array $users An array of users to create. * @return array An array of arrays + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::create_users() */ public static function create_users($users) { return core_user_external::create_users($users); @@ -667,8 +713,12 @@ public static function create_users($users) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_user_external::create_users_returns instead + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::create_users_returns() */ public static function create_users_returns() { return core_user_external::create_users_returns(); @@ -677,8 +727,12 @@ public static function create_users_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_user_external::delete_users_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::delete_users_parameters() */ public static function delete_users_parameters() { return core_user_external::delete_users_parameters(); @@ -686,9 +740,13 @@ public static function delete_users_parameters() { /** * Delete users - * @deprecated since Moodle 2.2 please use core_user_external::delete_users instead + * * @param array $userids * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::delete_users() */ public static function delete_users($userids) { return core_user_external::delete_users($userids); @@ -696,8 +754,12 @@ public static function delete_users($userids) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_user_external::delete_users_returns instead - * @return external_description + * + * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::delete_users_returns() */ public static function delete_users_returns() { return core_user_external::delete_users_returns(); @@ -706,8 +768,12 @@ public static function delete_users_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_user_external::update_users_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::update_users_parameters() */ public static function update_users_parameters() { return core_user_external::update_users_parameters(); @@ -715,9 +781,13 @@ public static function update_users_parameters() { /** * Update users - * @deprecated since Moodle 2.2 please use core_user_external::update_users instead + * * @param array $users * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::update_users() */ public static function update_users($users) { return core_user_external::update_users($users); @@ -725,8 +795,12 @@ public static function update_users($users) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_user_external::update_users_returns instead - * @return external_description + * + * @return null + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::update_users_returns() */ public static function update_users_returns() { return core_user_external::update_users_returns(); @@ -734,8 +808,12 @@ public static function update_users_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id_parameters instead + * * @return external_function_parameters + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::get_users_by_id_parameters() */ public static function get_users_by_id_parameters() { return core_user_external::get_users_by_id_parameters(); @@ -746,9 +824,13 @@ public static function get_users_by_id_parameters() { * - This function is matching the permissions of /user/profil.php * - It is also matching some permissions from /user/editadvanced.php for the following fields: * auth, confirmed, idnumber, lang, theme, timezone, mailformat - * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id instead + * * @param array $userids array of user ids * @return array An array of arrays describing users + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::get_users_by_id() */ public static function get_users_by_id($userids) { return core_user_external::get_users_by_id($userids); @@ -756,16 +838,24 @@ public static function get_users_by_id($userids) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id_returns instead + * * @return external_description + * @since Moodle 2.0 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::get_users_by_id_returns() */ public static function get_users_by_id_returns() { return core_user_external::get_users_by_id_returns(); } /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles_parameters instead + * * @return external_function_parameters + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::get_course_user_profiles_parameters() */ public static function get_course_participants_by_id_parameters() { return core_user_external::get_course_user_profiles_parameters(); @@ -773,9 +863,13 @@ public static function get_course_participants_by_id_parameters() { /** * Get course participant's details - * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles instead + * * @param array $userlist array of user ids and according course ids * @return array An array of arrays describing course participants + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::get_course_user_profiles() */ public static function get_course_participants_by_id($userlist) { return core_user_external::get_course_user_profiles($userlist); @@ -783,8 +877,12 @@ public static function get_course_participants_by_id($userlist) { /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles_returns instead + * * @return external_description + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_user_external::get_course_user_profiles_returns() */ public static function get_course_participants_by_id_returns() { return core_user_external::get_course_user_profiles_returns(); @@ -792,8 +890,12 @@ public static function get_course_participants_by_id_returns() { /** * Returns description of method parameters - * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_parameters instead + * * @return external_function_parameters + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_enrolled_users_parameters() */ public static function get_users_by_courseid_parameters() { global $CFG; @@ -803,13 +905,17 @@ public static function get_users_by_courseid_parameters() { /** * Get course participants details - * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users instead + * * @param int $courseid course id * @param array $options options { - * 'name' => option name - * 'value' => option value - * } + * 'name' => option name + * 'value' => option value + * } * @return array An array of users + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_enrolled_users() */ public static function get_users_by_courseid($courseid, $options) { global $CFG; @@ -818,8 +924,12 @@ public static function get_users_by_courseid($courseid, $options) { } /** * Returns description of method result value - * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_returns instead + * * @return external_description + * @since Moodle 2.1 + * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. + * @todo MDL-31194 This will be deleted in Moodle 2.5. + * @see core_enrol_external::get_enrolled_users_returns() */ public static function get_users_by_courseid_returns() { global $CFG;