From 77c13e2847bfdb597e174a007cc5b1e1ba11c0bb Mon Sep 17 00:00:00 2001 From: PMKuipers Date: Sun, 27 Aug 2023 21:57:21 +0200 Subject: [PATCH] PHPDoc documentation --- classes/associationservice.php | 80 +++++++++ classes/badgeinfo.php | 19 +++ classes/corecompletioninfo.php | 93 +++++++++- classes/courseinfo.php | 19 +++ classes/gradeinfo.php | 10 ++ classes/studentstudyplanservice.php | 56 ++++++ classes/studyitem.php | 23 +++ classes/studyline.php | 23 +++ classes/studyplan.php | 27 +++ classes/studyplanpage.php | 23 +++ classes/studyplanservice.php | 256 ++++++++++++++++++++++++++++ 11 files changed, 626 insertions(+), 3 deletions(-) diff --git a/classes/associationservice.php b/classes/associationservice.php index 627527e..9246247 100644 --- a/classes/associationservice.php +++ b/classes/associationservice.php @@ -100,6 +100,10 @@ class associationservice extends \external_api { } + /** + * Parameter description for webservice function list_cohort + * @return \external_function_parameters + */ public static function list_cohort_parameters() { return new \external_function_parameters( [ 'like' => new \external_value(PARAM_TEXT, 'search text', VALUE_OPTIONAL), @@ -108,6 +112,10 @@ class associationservice extends \external_api { ] ); } + /** + * Return value description for webservice function list_cohort + * @return \external_description + */ public static function list_cohort_returns() { return new \external_multiple_structure(self::cohort_structure()); } @@ -146,6 +154,10 @@ class associationservice extends \external_api { return $cohorts; } + /** + * Parameter description for webservice function find_user + * @return \external_function_parameters + */ public static function find_user_parameters() { return new \external_function_parameters( [ 'like' => new \external_value(PARAM_TEXT, 'search text'), @@ -154,6 +166,10 @@ class associationservice extends \external_api { ] ); } + /** + * Return value description for webservice function find_user + * @return \external_description + */ public static function find_user_returns() { return new \external_multiple_structure(self::user_structure()); } @@ -189,6 +205,10 @@ class associationservice extends \external_api { return $users; } + /** + * Parameter description for webservice function connect_cohort + * @return \external_function_parameters + */ public static function connect_cohort_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), @@ -196,6 +216,10 @@ class associationservice extends \external_api { ] ); } + /** + * Return value description for webservice function connect_cohort + * @return \external_description + */ public static function connect_cohort_returns() { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), @@ -225,6 +249,10 @@ class associationservice extends \external_api { } + /** + * Parameter description for webservice function disconnect_cohort + * @return \external_function_parameters + */ public static function disconnect_cohort_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), @@ -232,6 +260,10 @@ class associationservice extends \external_api { ] ); } + /** + * Return value description for webservice function disconnect_cohort + * @return \external_description + */ public static function disconnect_cohort_returns() { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), @@ -261,6 +293,10 @@ class associationservice extends \external_api { } + /** + * Parameter description for webservice function connect_user + * @return \external_function_parameters + */ public static function connect_user_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), @@ -268,6 +304,10 @@ class associationservice extends \external_api { ] ); } + /** + * Return value description for webservice function connect_user + * @return \external_description + */ public static function connect_user_returns() { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), @@ -296,6 +336,10 @@ class associationservice extends \external_api { } } + /** + * Parameter description for webservice function disconnect_user + * @return \external_function_parameters + */ public static function disconnect_user_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), @@ -303,6 +347,10 @@ class associationservice extends \external_api { ] ); } + /** + * Return value description for webservice function disconnect_user + * @return \external_description + */ public static function disconnect_user_returns() { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), @@ -330,12 +378,20 @@ class associationservice extends \external_api { } } + /** + * Parameter description for webservice function associated_users + * @return \external_function_parameters + */ public static function associated_users_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); } + /** + * Return value description for webservice function associated_users + * @return \external_description + */ public static function associated_users_returns() { return new \external_multiple_structure(self::user_structure()); } @@ -359,12 +415,20 @@ class associationservice extends \external_api { return $users; } + /** + * Parameter description for webservice function associated_cohorts + * @return \external_function_parameters + */ public static function associated_cohorts_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); } + /** + * Return value description for webservice function associated_cohorts + * @return \external_description + */ public static function associated_cohorts_returns() { return new \external_multiple_structure(self::cohort_structure()); } @@ -386,12 +450,20 @@ class associationservice extends \external_api { return $cohorts; } + /** + * Parameter description for webservice function all_associated + * @return \external_function_parameters + */ public static function all_associated_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); } + /** + * Return value description for webservice function all_associated + * @return \external_description + */ public static function all_associated_returns() { return new \external_multiple_structure(self::user_structure()); } @@ -443,12 +515,20 @@ class associationservice extends \external_api { }); } + /** + * Parameter description for webservice function cascade_cohortsync + * @return \external_function_parameters + */ public static function cascade_cohortsync_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); } + /** + * Return value description for webservice function cascade_cohortsync + * @return \external_description + */ public static function cascade_cohortsync_returns() { return success::structure(); } diff --git a/classes/badgeinfo.php b/classes/badgeinfo.php index 97a041e..20b5bc2 100644 --- a/classes/badgeinfo.php +++ b/classes/badgeinfo.php @@ -63,6 +63,11 @@ class badgeinfo { return is_numeric($id) && $DB->record_exists('badge', array('id' => $id)); } + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of badge'), @@ -81,6 +86,10 @@ class badgeinfo { ], "Badge info", $value); } + /** + * Webservice model for editor info + * @return array Webservice data model + */ public function editor_model(array $studentlist = null) { if ($this->badge->type == BADGE_TYPE_SITE) { $context = \context_system::instance(); @@ -114,6 +123,11 @@ class badgeinfo { return $model; } + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of badge'), @@ -132,6 +146,11 @@ class badgeinfo { ], "Badge info", $value); } + /** + * Webservice model for user info + * @param int $userid ID of user to check specific info for + * @return array Webservice data model + */ public function user_model($userid) { global $DB; if ($this->badge->type == BADGE_TYPE_SITE) { diff --git a/classes/corecompletioninfo.php b/classes/corecompletioninfo.php index b4d9a30..8f6337e 100644 --- a/classes/corecompletioninfo.php +++ b/classes/corecompletioninfo.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Class to collect course completion info for a given course * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -33,16 +33,36 @@ use \grade_item; use \grade_scale; use \grade_outcome; +/** + * Class to collect course completion info for a given course + */ class corecompletioninfo { + /** @var \stdClass */ private $course; + /** @var \completion_info */ private $completion; + /** @var \course_modinfo */ private $modinfo; + + /** + * Cached dict of completion:: constants to equivalent webservice strings + * @var array */ private static $completionhandles = null; + /** + * Cached dict of all completion type constants to equivalent strings + * @var array */ private static $completiontypes = null; + /** + * Course id of relevant course + */ public function id() { return $this->course->id; } + /** + * Construct new object for a given course + * @param \stdClass $course Course database record + */ public function __construct($course) { global $DB; $this->course = $course; @@ -50,6 +70,10 @@ class corecompletioninfo { $this->modinfo = get_fast_modinfo($this->course); } + /** + * Get dictionary of all completion types as CONST => 'string' + * @return array + */ public static function completiontypes() { /* While it is tempting to use the global array COMPLETION_CRITERIA_TYPES, so we don't have to manually add any completion types if moodle decides to add a few. @@ -79,7 +103,7 @@ class corecompletioninfo { /** * Translate a numeric completion constant to a text string - * @param $completion The completion code as defined in completionlib.php to translate to a text handle + * @param int $completion The completion code as defined in completionlib.php to translate to a text handle */ public static function completion_handle($completion) { if (empty(self::$completionhandles)) { @@ -94,6 +118,11 @@ class corecompletioninfo { return self::$completionhandles[$completion] ?? "undefined"; } + /** + * Webservice editor structure for completion_item + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function completion_item_editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'criteria id', VALUE_OPTIONAL), @@ -109,6 +138,11 @@ class corecompletioninfo { ], 'completion type', $value); } + /** + * Webservice editor structure for completion_type + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function completion_type_editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "items" => new \external_multiple_structure(self::completion_item_editor_structure(), 'subitems', VALUE_OPTIONAL), @@ -119,6 +153,16 @@ class corecompletioninfo { ], 'completion type', $value); } + /** + * Webservice editor structure for course completion + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "conditions" => new \external_multiple_structure(self::completion_type_editor_structure(), 'completion conditions'), @@ -127,6 +171,11 @@ class corecompletioninfo { ], 'course completion info', $value); } + /** + * Webservice user view structure for completion_item + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function completion_item_user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of completion', VALUE_OPTIONAL), @@ -148,6 +197,11 @@ class corecompletioninfo { ], 'completion type', $value); } + /** + * Webservice user view structure for completion_type + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function completion_type_user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "items" => new \external_multiple_structure(self::completion_item_user_structure(), 'subitems', VALUE_OPTIONAL), @@ -163,6 +217,16 @@ class corecompletioninfo { ], 'completion type', $value); } + /** + * Webservice user view structure for course completion + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "progress" => new \external_value(PARAM_INT, 'completed sub-conditions'), @@ -176,10 +240,19 @@ class corecompletioninfo { ], 'course completion info', $value); } + /** + * Convert agregation method constant to equivalent string for webservice + * @param int $method COMPLETION_AGGREGATION_ALL || COMPLETION_AGGREGATION_ANY + * @return string 'all' or 'any' + */ private static function aggregation_handle($method) { return ($method == COMPLETION_AGGREGATION_ALL) ? "all" : "any"; } + /** + * Webservice model for editor info + * @return array Webservice data model + */ public function editor_model() { global $DB, $CFG; @@ -338,6 +411,12 @@ class corecompletioninfo { return $info; } + /** + * Determine overall completion for a given type + * @param int $typeaggregation COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY + * @param \completion_criteria_completion[] $completions List of completions to aggregate + * @return bool Completed or not + */ private function aggregate_completions($typeaggregation, $completions) { $completed = 0; $count = count($completions); @@ -354,6 +433,11 @@ class corecompletioninfo { } + /** + * Webservice model for user course completion info + * @param int $userid ID of user to check specific info for + * @return array Webservice data model + */ public function user_model($userid) { global $DB; @@ -464,6 +548,8 @@ class corecompletioninfo { /** * Get the grade for a certain course module + * @param \cm_info $cm Course module + * @param int $userid ID of user to retrieve grade for * @return stdClass|null object containing 'grade' and optional 'feedback' attribute */ private function get_grade($cm, $userid) { @@ -507,7 +593,8 @@ class corecompletioninfo { } /** - * Get the grade for a certain course module + * Get the overall grade for this course + * @param int $userid ID of user to retrieve grade for * @return stdClass|null object containing 'grade' and optional 'feedback' attribute */ private function get_course_grade($userid) { diff --git a/classes/courseinfo.php b/classes/courseinfo.php index d27a15b..e467856 100644 --- a/classes/courseinfo.php +++ b/classes/courseinfo.php @@ -181,6 +181,11 @@ class courseinfo { return $info; } + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'linked course id'), @@ -202,6 +207,10 @@ class courseinfo { ], 'referenced course information', $value); } + /** + * Webservice model for editor info + * @return array Webservice data model + */ public function editor_model(studyitem $studyitem = null, $usecorecompletioninfo = false) { global $DB; $contextinfo = new contextinfo($this->context); @@ -239,6 +248,11 @@ class courseinfo { return $info; } + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'linked course id'), @@ -255,6 +269,11 @@ class courseinfo { ], 'course information', $value); } + /** + * Webservice model for user info + * @param int $userid ID of user to check specific info for + * @return array Webservice data model + */ public function user_model($userid, $usecorecompletioninfo = false) { global $DB; $contextinfo = new contextinfo($this->context); diff --git a/classes/gradeinfo.php b/classes/gradeinfo.php index 4b49573..38190f2 100644 --- a/classes/gradeinfo.php +++ b/classes/gradeinfo.php @@ -253,6 +253,11 @@ class gradeinfo { * @param int $value Webservice requirement constant * @return external_single_structure Webservice output structure */ + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'grade_item id'), @@ -302,6 +307,11 @@ class gradeinfo { * @param int $value Webservice requirement constant * @return external_single_structure Webservice output structure */ + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'grade_item id'), diff --git a/classes/studentstudyplanservice.php b/classes/studentstudyplanservice.php index 7d6e31e..b4f1524 100644 --- a/classes/studentstudyplanservice.php +++ b/classes/studentstudyplanservice.php @@ -37,12 +37,20 @@ class studentstudyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function list_user_studyplans + * @return \external_function_parameters + */ public static function list_user_studyplans_parameters() { return new \external_function_parameters([ "userid" => new \external_value(PARAM_INT, 'id of student', VALUE_DEFAULT), ]); } + /** + * Return value description for webservice function list_user_studyplans + * @return \external_description + */ public static function list_user_studyplans_returns() { return new \external_multiple_structure( studyplan::simple_structure() @@ -69,12 +77,20 @@ class studentstudyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function get_user_studyplans + * @return \external_function_parameters + */ public static function get_user_studyplans_parameters() { return new \external_function_parameters( [ "userid" => new \external_value(PARAM_INT, 'id of user'), ] ); } + /** + * Return value description for webservice function get_user_studyplans + * @return \external_description + */ public static function get_user_studyplans_returns() { return new \external_multiple_structure( studyplan::user_structure() @@ -102,6 +118,10 @@ class studentstudyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function get_user_studyplan + * @return \external_function_parameters + */ public static function get_user_studyplan_parameters() { return new \external_function_parameters( [ "userid" => new \external_value(PARAM_INT, 'id of user'), @@ -109,6 +129,10 @@ class studentstudyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function get_user_studyplan + * @return \external_description + */ public static function get_user_studyplan_returns() { return studyplan::user_structure(); } @@ -131,12 +155,20 @@ class studentstudyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function get_invited_studyplan + * @return \external_function_parameters + */ public static function get_invited_studyplan_parameters() { return new \external_function_parameters( [ "invitekey" => new \external_value(PARAM_RAW, 'invite key'), ] ); } + /** + * Return value description for webservice function get_invited_studyplan + * @return \external_description + */ public static function get_invited_studyplan_returns() { return new \external_multiple_structure( studyplan::user_structure() @@ -174,10 +206,18 @@ class studentstudyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function list_own_studyplans + * @return \external_function_parameters + */ public static function list_own_studyplans_parameters() { return new \external_function_parameters([]); } + /** + * Return value description for webservice function list_own_studyplans + * @return \external_description + */ public static function list_own_studyplans_returns() { return new \external_multiple_structure( studyplan::simple_structure() @@ -202,12 +242,20 @@ class studentstudyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function get_own_studyplan + * @return \external_function_parameters + */ public static function get_own_studyplan_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of specific studyplan to provide', VALUE_DEFAULT), ] ); } + /** + * Return value description for webservice function get_own_studyplan + * @return \external_description + */ public static function get_own_studyplan_returns() { return new \external_multiple_structure( studyplan::user_structure() @@ -246,12 +294,20 @@ class studentstudyplanservice extends \external_api { * * ***************************/ + /** + * Parameter description for webservice function get_teaching_studyplans + * @return \external_function_parameters + */ public static function get_teaching_studyplans_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of specific studyplan to provide', VALUE_DEFAULT), ] ); } + /** + * Return value description for webservice function get_teaching_studyplans + * @return \external_description + */ public static function get_teaching_studyplans_returns() { return new \external_multiple_structure( studyplan::editor_structure() diff --git a/classes/studyitem.php b/classes/studyitem.php index 214ff04..842e77b 100644 --- a/classes/studyitem.php +++ b/classes/studyitem.php @@ -105,6 +105,11 @@ class studyitem { return is_numeric($id) && $DB->record_exists(self::TABLE, array('id' => $id)); } + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of study item'), @@ -124,6 +129,10 @@ class studyitem { } + /** + * Webservice model for editor info + * @return array Webservice data model + */ public function editor_model() { return $this->generate_model("editor"); } @@ -343,6 +352,11 @@ class studyitem { ]; } + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of study item'), @@ -362,6 +376,11 @@ class studyitem { } + /** + * Webservice model for user info + * @param int $userid ID of user to check specific info for + * @return array Webservice data model + */ public function user_model($userid) { global $CFG, $DB; @@ -503,6 +522,10 @@ class studyitem { return $new; } + /** + * Export essential information for export + * @return array information model + */ public function export_model() { return $this->generate_model("export"); } diff --git a/classes/studyline.php b/classes/studyline.php index a9a3367..77015cc 100644 --- a/classes/studyline.php +++ b/classes/studyline.php @@ -97,6 +97,11 @@ class studyline { return $this->r->shortname; } + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyline'), @@ -115,6 +120,10 @@ class studyline { ]); } + /** + * Webservice model for editor info + * @return array Webservice data model + */ public function editor_model() { return $this->generate_model("editor"); } @@ -261,6 +270,11 @@ class studyline { return $list; } + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyline'), @@ -279,6 +293,11 @@ class studyline { ], 'Studyline with user info', $value); } + /** + * Webservice model for user info + * @param int $userid ID of user to check specific info for + * @return array Webservice data model + */ public function user_model($userid) { // TODO: Integrate this function into generate_model() for ease of maintenance. @@ -357,6 +376,10 @@ class studyline { return $new; } + /** + * Export essential information for export + * @return array information model + */ public function export_model() { return $this->generate_model("export"); } diff --git a/classes/studyplan.php b/classes/studyplan.php index a80f0bb..aae6d29 100644 --- a/classes/studyplan.php +++ b/classes/studyplan.php @@ -138,6 +138,11 @@ class studyplan { ]; } + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan'), @@ -161,6 +166,10 @@ class studyplan { ], 'Studyplan full structure', $value); } + /** + * Webservice model for editor info + * @return array Webservice data model + */ public function editor_model() { global $DB; @@ -451,6 +460,11 @@ class studyplan { } } + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan'), @@ -464,6 +478,11 @@ class studyplan { } + /** + * Webservice model for user info + * @param int $userid ID of user to check specific info for + * @return array Webservice data model + */ public function user_model($userid) { $model = [ @@ -522,6 +541,10 @@ class studyplan { return [ "format" => "application/json", "content" => $json]; } + /** + * Export essential information for export + * @return array information model + */ public function export_model() { $model = [ 'name' => $this->r->name, @@ -535,6 +558,10 @@ class studyplan { return $model; } + /** + * Export all pages + * @return array information model + */ public function export_pages_model() { $pages = []; foreach ($this->pages() as $p) { diff --git a/classes/studyplanpage.php b/classes/studyplanpage.php index 3ebd899..0837555 100644 --- a/classes/studyplanpage.php +++ b/classes/studyplanpage.php @@ -120,6 +120,11 @@ class studyplanpage { ]; } + /** + * Webservice structure for editor info + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function editor_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan'), @@ -134,6 +139,10 @@ class studyplanpage { ], 'Studyplan page full structure', $value); } + /** + * Webservice model for editor info + * @return array Webservice data model + */ public function editor_model() { global $DB; @@ -218,6 +227,11 @@ class studyplanpage { } } + /** + * Webservice structure for userinfo + * @param int $value Webservice requirement constant + * @return \external_single_structure Webservice output structure + */ public static function user_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan page'), @@ -232,6 +246,11 @@ class studyplanpage { ], 'Studyplan page with user info', $value); } + /** + * Webservice model for user info + * @param int $userid ID of user to check specific info for + * @return array Webservice data model + */ public function user_model($userid) { $model = [ @@ -416,6 +435,10 @@ class studyplanpage { return [ "format" => "application/json", "content" => $json]; } + /** + * Export essential information for export + * @return array information model + */ public function export_model() { $model = [ 'fullname' => $this->r->fullname, diff --git a/classes/studyplanservice.php b/classes/studyplanservice.php index 8bd96df..c2c1f9c 100644 --- a/classes/studyplanservice.php +++ b/classes/studyplanservice.php @@ -41,12 +41,20 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function list_studyplans + * @return \external_function_parameters + */ public static function list_studyplans_parameters() { return new \external_function_parameters([ "context_id" => new \external_value(PARAM_INT, 'context to search in for studyplans', VALUE_DEFAULT), ]); } + /** + * Return value description for webservice function list_studyplans + * @return \external_description + */ public static function list_studyplans_returns() { return new \external_multiple_structure( studyplan::simple_structure() ); } @@ -74,12 +82,20 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function get_studyplan_map + * @return \external_function_parameters + */ public static function get_studyplan_map_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of a studyplan to check usage on', VALUE_REQUIRED), ] ); } + /** + * Return value description for webservice function get_studyplan_map + * @return \external_description + */ public static function get_studyplan_map_returns() { return studyplan::editor_structure(); } @@ -100,12 +116,20 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function get_studyline_map + * @return \external_function_parameters + */ public static function get_studyline_map_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of a studyline to check usage on', VALUE_DEFAULT), ]); } + /** + * Return value description for webservice function get_studyline_map + * @return \external_description + */ public static function get_studyline_map_returns() { return new \external_multiple_structure( studyline::editor_structure() ); } @@ -123,6 +147,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function add_studyplan + * @return \external_function_parameters + */ public static function add_studyplan_parameters() { return new \external_function_parameters( [ "name" => new \external_value(PARAM_TEXT, 'name of studyplan'), @@ -138,6 +166,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function add_studyplan + * @return \external_description + */ public static function add_studyplan_returns() { return studyplan::simple_structure(); } @@ -169,6 +201,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function edit_studyplan + * @return \external_function_parameters + */ public static function edit_studyplan_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyplan'), @@ -185,6 +221,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function edit_studyplan + * @return \external_description + */ public static function edit_studyplan_returns() { return studyplan::simple_structure(); } @@ -220,6 +260,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function delete_studyplan + * @return \external_function_parameters + */ public static function delete_studyplan_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyplan'), @@ -227,6 +271,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function delete_studyplan + * @return \external_description + */ public static function delete_studyplan_returns() { return success::structure(); } @@ -244,6 +292,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function add_studyline + * @return \external_function_parameters + */ public static function add_studyline_parameters() { return new \external_function_parameters( [ "page_id" => new \external_value(PARAM_INT, 'id of studyplan to add line to'), @@ -254,6 +306,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function add_studyline + * @return \external_description + */ public static function add_studyline_returns() { return studyline::editor_structure(); } @@ -279,6 +335,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function edit_studyline + * @return \external_function_parameters + */ public static function edit_studyline_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyline'), @@ -288,6 +348,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function edit_studyline + * @return \external_description + */ public static function edit_studyline_returns() { return studyline::editor_structure(); } @@ -311,12 +375,20 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function delete_studyline + * @return \external_function_parameters + */ public static function delete_studyline_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyline'), ] ); } + /** + * Return value description for webservice function delete_studyline + * @return \external_description + */ public static function delete_studyline_returns() { return success::structure(); } @@ -335,6 +407,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function reorder_studylines + * @return \external_function_parameters + */ public static function reorder_studylines_parameters() { return new \external_function_parameters( [ "sequence" => new \external_multiple_structure( @@ -346,6 +422,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function reorder_studylines + * @return \external_description + */ public static function reorder_studylines_returns() { return success::structure(); } @@ -370,12 +450,20 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function get_studyitem + * @return \external_function_parameters + */ public static function get_studyitem_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of a study item to retrieve'), ] ); } + /** + * Return value description for webservice function get_studyitem + * @return \external_description + */ public static function get_studyitem_returns() { return studyitem::editor_structure(); } @@ -393,6 +481,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function add_studyitem + * @return \external_function_parameters + */ public static function add_studyitem_parameters() { return new \external_function_parameters( [ "line_id" => new \external_value(PARAM_INT, 'id of related study line'), @@ -409,6 +501,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function add_studyitem + * @return \external_description + */ public static function add_studyitem_returns() { return studyitem::editor_structure(); } @@ -435,6 +531,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function edit_studyitem + * @return \external_function_parameters + */ public static function edit_studyitem_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of study item'), @@ -443,6 +543,10 @@ class studyplanservice extends \external_api { ]); } + /** + * Return value description for webservice function edit_studyitem + * @return \external_description + */ public static function edit_studyitem_returns() { return studyitem::editor_structure(); } @@ -470,6 +574,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function reorder_studyitems + * @return \external_function_parameters + */ public static function reorder_studyitems_parameters() { return new \external_function_parameters( [ "items" => new \external_multiple_structure( @@ -483,6 +591,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function reorder_studyitems + * @return \external_description + */ public static function reorder_studyitems_returns() { return success::structure(); } @@ -502,12 +614,20 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function delete_studyitem + * @return \external_function_parameters + */ public static function delete_studyitem_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyitem'), ] ); } + /** + * Return value description for webservice function delete_studyitem + * @return \external_description + */ public static function delete_studyitem_returns() { return success::structure(); } @@ -525,6 +645,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function connect_studyitems + * @return \external_function_parameters + */ public static function connect_studyitems_parameters() { return new \external_function_parameters( [ "from_id" => new \external_value(PARAM_INT, 'id of studyitem connect start '), @@ -532,6 +656,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function connect_studyitems + * @return \external_description + */ public static function connect_studyitems_returns() { return studyitemconnection::structure(); } @@ -551,6 +679,10 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function disconnect_studyitems + * @return \external_function_parameters + */ public static function disconnect_studyitems_parameters() { return new \external_function_parameters( [ "from_id" => new \external_value(PARAM_INT, 'id of studyitem '), @@ -558,6 +690,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function disconnect_studyitems + * @return \external_description + */ public static function disconnect_studyitems_returns() { return success::structure(); } @@ -575,10 +711,18 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function list_badges + * @return \external_function_parameters + */ public static function list_badges_parameters() { return new \external_function_parameters( [] ); } + /** + * Return value description for webservice function list_badges + * @return \external_description + */ public static function list_badges_returns() { return new \external_multiple_structure(badgeinfo::editor_structure()); } @@ -605,6 +749,10 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function include_grade + * @return \external_function_parameters + */ public static function include_grade_parameters() { return new \external_function_parameters( [ "grade_id" => new \external_value(PARAM_INT, 'id of gradeitem '), @@ -614,6 +762,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function include_grade + * @return \external_description + */ public static function include_grade_returns() { return success::structure(); } @@ -642,10 +794,18 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function list_aggregators + * @return \external_function_parameters + */ public static function list_aggregators_parameters() { return new \external_function_parameters([]); } + /** + * Return value description for webservice function list_aggregators + * @return \external_description + */ public static function list_aggregators_returns() { return aggregator::list_structure(); } @@ -661,6 +821,10 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function force_studyplan_scale + * @return \external_function_parameters + */ public static function force_studyplan_scale_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan'), @@ -668,6 +832,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function force_studyplan_scale + * @return \external_description + */ public static function force_studyplan_scale_returns() { return new \external_multiple_structure(new \external_single_structure([ "course" => courseinfo::simple_structure(), @@ -780,10 +948,18 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function list_scales + * @return \external_function_parameters + */ public static function list_scales_parameters() { return new \external_function_parameters( [] ); } + /** + * Return value description for webservice function list_scales + * @return \external_description + */ public static function list_scales_returns() { return new \external_multiple_structure(new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of scale'), @@ -813,12 +989,20 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function disable_autoenddate + * @return \external_function_parameters + */ public static function disable_autoenddate_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan'), ] ); } + /** + * Return value description for webservice function disable_autoenddate + * @return \external_description + */ public static function disable_autoenddate_returns() { return success::structure(); } @@ -856,6 +1040,10 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function duplicate_plan + * @return \external_function_parameters + */ public static function duplicate_plan_parameters() { return new \external_function_parameters( [ "plan_id" => new \external_value(PARAM_INT, 'id of plan to copy '), @@ -864,6 +1052,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function duplicate_plan + * @return \external_description + */ public static function duplicate_plan_returns() { return studyplan::simple_structure(); } @@ -881,6 +1073,10 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function export_plan + * @return \external_function_parameters + */ public static function export_plan_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '), @@ -888,6 +1084,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function export_plan + * @return \external_description + */ public static function export_plan_returns() { return studyplan::export_structure(); } @@ -909,12 +1109,20 @@ class studyplanservice extends \external_api { } } + /** + * Parameter description for webservice function export_studylines + * @return \external_function_parameters + */ public static function export_studylines_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '), ] ); } + /** + * Return value description for webservice function export_studylines + * @return \external_description + */ public static function export_studylines_returns() { return studyplan::export_structure(); } @@ -937,6 +1145,10 @@ class studyplanservice extends \external_api { * * ****************************/ + /** + * Parameter description for webservice function import_plan + * @return \external_function_parameters + */ public static function import_plan_parameters() { return new \external_function_parameters( [ "content" => new \external_value(PARAM_TEXT, 'import file content'), @@ -945,6 +1157,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function import_plan + * @return \external_description + */ public static function import_plan_returns() { return success::structure(); } @@ -963,6 +1179,10 @@ class studyplanservice extends \external_api { } } + /** + * Parameter description for webservice function import_studylines + * @return \external_function_parameters + */ public static function import_studylines_parameters() { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '), @@ -971,6 +1191,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function import_studylines + * @return \external_description + */ public static function import_studylines_returns() { return success::structure(); } @@ -998,6 +1222,10 @@ class studyplanservice extends \external_api { * * ********************************************************/ + /** + * Parameter description for webservice function submit_cm_editform + * @return \external_function_parameters + */ public static function submit_cm_editform_parameters() { return new \external_function_parameters( [ "cmid" => new \external_value(PARAM_INT, 'id of course module'), @@ -1005,6 +1233,10 @@ class studyplanservice extends \external_api { ] ); } + /** + * Return value description for webservice function submit_cm_editform + * @return \external_description + */ public static function submit_cm_editform_returns() { return success::structure(); } @@ -1075,6 +1307,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function edit_period + * @return \external_function_parameters + */ public static function edit_period_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of study item'), @@ -1085,6 +1321,10 @@ class studyplanservice extends \external_api { ]); } + /** + * Return value description for webservice function edit_period + * @return \external_description + */ public static function edit_period_returns() { return period::structure(); } @@ -1110,6 +1350,10 @@ class studyplanservice extends \external_api { * * ************************/ + /** + * Parameter description for webservice function course_period_timing + * @return \external_function_parameters + */ public static function course_period_timing_parameters() { return new \external_function_parameters( [ "period_id" => new \external_value(PARAM_INT, 'Period number within page'), @@ -1118,6 +1362,10 @@ class studyplanservice extends \external_api { ]); } + /** + * Return value description for webservice function course_period_timing + * @return \external_description + */ public static function course_period_timing_returns() { return courseinfo::editor_structure(); } @@ -1175,6 +1423,10 @@ class studyplanservice extends \external_api { } } + /** + * Parameter description for webservice function set_studyitem_span + * @return \external_function_parameters + */ public static function set_studyitem_span_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of study item'), @@ -1182,6 +1434,10 @@ class studyplanservice extends \external_api { ]); } + /** + * Return value description for webservice function set_studyitem_span + * @return \external_description + */ public static function set_studyitem_span_returns() { return studyitem::editor_structure(); }