From 0f255458cb8041985a5fba6f6e38ecb369272cd8 Mon Sep 17 00:00:00 2001 From: PMKuipers Date: Sun, 27 Aug 2023 21:23:39 +0200 Subject: [PATCH] PHPDoc documentation --- classes/courseinfo.php | 1 + classes/courseservice.php | 154 +++++++++++++++++++++++++++++--- classes/gradeinfo.php | 142 ++++++++++++++++++++++++++--- classes/period.php | 7 ++ classes/studyitem.php | 7 ++ classes/studyitemconnection.php | 73 +++++++++++++-- classes/studyline.php | 7 ++ classes/studyplan.php | 8 ++ classes/studyplanpage.php | 7 ++ classes/teachingfinder.php | 1 + 10 files changed, 377 insertions(+), 30 deletions(-) diff --git a/classes/courseinfo.php b/classes/courseinfo.php index f77aea7..d27a15b 100644 --- a/classes/courseinfo.php +++ b/classes/courseinfo.php @@ -34,6 +34,7 @@ use \grade_scale; use \grade_outcome; class courseinfo { + /** @var string */ const TABLE = 'course'; private $course; diff --git a/classes/courseservice.php b/classes/courseservice.php index 2e25357..62d50ba 100644 --- a/classes/courseservice.php +++ b/classes/courseservice.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Webservice related to courses * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -30,27 +30,48 @@ use \local_treestudyplan\associationservice; use \local_treestudyplan\local\helpers\webservicehelper; use \local_treestudyplan\completionscanner; use \local_treestudyplan\gradingscanner; +use \core_course_category; +/** + * Webservice related to courses + */ class courseservice extends \external_api { + /** + * Capability required to edit study plans + * @var string + */ const CAP_EDIT = "local/treestudyplan:editstudyplan"; + /** + * Capability required to view studyplans (for other users) + * @var string + */ const CAP_VIEW = "local/treestudyplan:viewuserreports"; - /************************ - * * - * list_courses * - * * - ************************/ + /** + * Return value description for map_categories function + * @return \external_description + */ public static function map_categories_parameters() { return new \external_function_parameters( [ "root_id" => new \external_value(PARAM_INT, 'root category to use as base', VALUE_DEFAULT), ] ); } + /** + * Parameter description for map_categories function + * @return \external_description + */ public static function map_categories_returns() { return new \external_multiple_structure(static::map_category_structure(false)); } + /** + * Structure description for category map, used in a number of return descriptions + * @param bool $lazy + * @param int $value + * @return \external_description + */ protected static function map_category_structure($lazy = false, $value = VALUE_REQUIRED) { $s = [ "id" => new \external_value(PARAM_INT, 'course category id'), @@ -68,6 +89,12 @@ class courseservice extends \external_api { return new \external_single_structure($s, "CourseCat info", $value); } + /** + * Get a category map, and optionally specify a root category to search for + * User's top category will be used if none specified + * @param int $rootid Optional starting category for the map + * @return array + */ public static function map_categories($rootid = 0) { global $CFG, $DB; @@ -97,22 +124,41 @@ class courseservice extends \external_api { return $list; } + /** + * Return value description for get_category function + * @return \external_description + */ public static function get_category_parameters() { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of category'), ] ); } + /** + * Parameter description for get_category function + * @return \external_description + */ public static function get_category_returns() { return static::map_category_structure(false); } + /** + * Get category info by id + * @param mixed $id + * @return array + */ public static function get_category($id) { $cat = \core_course_category::get($id); return static::map_category($cat); } - protected static function map_category(\core_course_category $cat, $lazy = false) { + /** + * Create a category map, given a specific category + * @param core_course_category $cat The category to scan + * @param bool $lazy If lazy loading, do not scan child categories + * @return array + */ + protected static function map_category(core_course_category $cat, $lazy = false) { global $DB; $catcontext = $cat->get_context(); $ctxinfo = new contextinfo($catcontext); @@ -142,16 +188,29 @@ class courseservice extends \external_api { return $model; } + /** + * Return value description for list_accessible_categories function + * @return \external_description + */ public static function list_accessible_categories_parameters() { return new \external_function_parameters( [ "operation" => new \external_value(PARAM_TEXT, 'type of operation ["view"|"edit"]', VALUE_DEFAULT), ] ); } + /** + * Parameter description for list_accessible_categories function + * @return \external_description + */ public static function list_accessible_categories_returns() { return new \external_multiple_structure(static::map_category_structure(true)); } + /** + * [Description for list_accessible_categories] + * @param string $operation + * @return array + */ public static function list_accessible_categories($operation = "edit") { if ($operation == "edit") { $capability = self::CAP_EDIT; @@ -170,7 +229,13 @@ class courseservice extends \external_api { } - public static function categories_by_capability($capability, \core_course_category $parent = null) { + /** + * [Description for categories_by_capability] + * @param mixed $capability + * @param core_course_category|null $parent + * @return array + */ + public static function categories_by_capability($capability, core_course_category $parent = null) { // List the categories in which the user has a specific capability. $list = []; // Initialize parent if needed. @@ -199,7 +264,12 @@ class courseservice extends \external_api { return $list; } - protected static function recursive_child_categories(\core_course_category $parent) { + /** + * Recursively create a list of all categories unter a specified parent + * @param core_course_category $parent + * @return core_course_category[] + */ + protected static function recursive_child_categories(core_course_category $parent) { $list = []; $children = $parent->get_children(); foreach ($children as $child) { @@ -211,16 +281,29 @@ class courseservice extends \external_api { return $list; } + /** + * Return value description for list_used_categories function + * @return \external_description + */ public static function list_used_categories_parameters() { return new \external_function_parameters( [ "operation" => new \external_value(PARAM_TEXT, 'type of operation ["view"|"edit"]', VALUE_DEFAULT), ]); } + /** + * Parameter description for list_used_categories function + * @return \external_description + */ public static function list_used_categories_returns() { return new \external_multiple_structure(static::map_category_structure(true)); } + /** + * List all categories available to the current user for editing or viewing studyplans + * @param string $operation The operation to scan usage for [edit, view] + * @return array + */ public static function list_used_categories($operation = 'edit') { global $DB; if ($operation == "edit") { @@ -255,6 +338,12 @@ class courseservice extends \external_api { return $list; } + /** + * List all categories available to the current user for editing or viewing studyplans and add information about their usage + * (Not a webservice function) + * @param string $operation + * @return stdClass[] + */ public static function list_accessible_categories_with_usage($operation = 'edit') { global $DB; if ($operation == "edit") { @@ -292,11 +381,15 @@ class courseservice extends \external_api { } /************************************** - * + * * Progress scanners for teacherview - * + * **************************************/ + /** + * Return value description for scan_grade_progress function + * @return external_function_parameters + */ public static function scan_grade_progress_parameters() { return new \external_function_parameters( [ "gradeitemid" => new \external_value(PARAM_INT, 'Grade item ID to scan progress for', VALUE_DEFAULT), @@ -305,10 +398,20 @@ class courseservice extends \external_api { ]); } + /** + * Parameter description for scan_grade_progress function + * @return \external_description + */ public static function scan_grade_progress_returns() { return gradingscanner::structure(VALUE_REQUIRED); } + /** + * Scan grade item for progress statistics + * @param mixed $gradeitemid Grade item id + * @param mixed $studyplanid Id of studyitem the grade is selected in + * @return array + */ public static function scan_grade_progress($gradeitemid, $studyplanid) { global $DB; // Verify access to the study plan. @@ -330,6 +433,10 @@ class courseservice extends \external_api { return $scanner->model(); } + /** + * Return value description for scan_completion_progress function + * @return \external_description + */ public static function scan_completion_progress_parameters() { return new \external_function_parameters( [ "criteriaid" => new \external_value(PARAM_INT, 'CriteriaID to scan progress for', VALUE_DEFAULT), @@ -338,10 +445,21 @@ class courseservice extends \external_api { ]); } + /** + * Parameter description for scan_completion_progress function + * @return \external_description + */ public static function scan_completion_progress_returns() { return completionscanner::structure(VALUE_REQUIRED); } + /** + * Scan criterium for progress statistics + * @param mixed $criteriaid Id of criterium + * @param mixed $studyplanid Id of studyplan relevant to this criteria + * @param mixed $courseid Id of course this cirteria is related to + * @return array + */ public static function scan_completion_progress($criteriaid, $studyplanid, $courseid) { global $DB; // Verify access to the study plan. @@ -357,6 +475,10 @@ class courseservice extends \external_api { return $scanner->model(); } + /** + * Return value description for scan_badge_progress function + * @return \external_description + */ public static function scan_badge_progress_parameters() { return new \external_function_parameters( [ "badgeid" => new \external_value(PARAM_INT, 'Badge to scan progress for', VALUE_DEFAULT), @@ -365,6 +487,10 @@ class courseservice extends \external_api { ]); } + /** + * Parameter description for scan_badge_progress function + * @return \external_description + */ public static function scan_badge_progress_returns() { return new \external_single_structure([ "total" => new \external_value(PARAM_INT, 'Total number of students scanned'), @@ -372,6 +498,12 @@ class courseservice extends \external_api { ]); } + /** + * Scan badge for completion progress statistica + * @param mixed $badgeid ID of the badge + * @param mixed $studyplanid ID of the relevant study plan + * @return array + */ public static function scan_badge_progress($badgeid, $studyplanid) { global $DB; // Check access to the study plan. diff --git a/classes/gradeinfo.php b/classes/gradeinfo.php index 740fb91..4b49573 100644 --- a/classes/gradeinfo.php +++ b/classes/gradeinfo.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Collect, process and display information about gradable items * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -29,34 +29,60 @@ require_once($CFG->dirroot.'/course/lib.php'); use core_course\local\repository\caching_content_item_readonly_repository; use core_course\local\repository\content_item_readonly_repository; +use core_course\local\entity\content_item; use \grade_item; use \grade_scale; use \grade_outcome; use \core_plugin_manager; - +/** + * Collect, process and display information about gradable items + */ class gradeinfo { + /** @var studyitem */ private $studyitem = null; + /** @var int */ private $id; + /** @var grade_item */ private $gradeitem; + /** @var string */ private $icon; + /** @var string */ private $link; + /** @var string */ private $gradinglink; + /** @var grade_scale*/ private $scale; + /** @var grade_outcome*/ private $outcome; + /** @var bool*/ private $hidden = false; + /** @var string */ private $name; + /** @var string */ private $typename; + /** @var int */ private $section; + /** @var int */ private $sectionorder; + /** @var int */ private $cmid; + /** @var int */ private $coursesort; + /** @var array */ private static $contentitems = null; + /** @var gradingscanner */ private $gradingscanner; + /** @var array */ private static $sections = []; + /** + * Get the sequence of activities for a given section id + * @param mixed $sectionid Id of section + * @return int[] Sequence of cms in a section + */ protected static function get_sectionsequence($sectionid) { global $DB; if (!array_key_exists($sectionid, self::$sections)) { @@ -65,19 +91,34 @@ class gradeinfo { return self::$sections[$sectionid]; } - public function get_gradeitem() { + /** + * Get the grade_item + * @return grade_item + */ + public function get_gradeitem() : grade_item { return $this->gradeitem; } - - public function get_gradingscanner() { + /** + * Get the gradingscanner + * @return gradingscanner + */ + public function get_gradingscanner() : gradingscanner{ return $this->gradingscanner; } - public function get_scale() { + /** + * Get the grade's scale if applicable + * @return grade_scale|null + */ + public function get_scale() : ?grade_scale{ return $this->scale; } - protected static function get_contentitems() { + /** + * Get content items (activity icons) from the repository + * @return content_item[] + */ + protected static function get_contentitems() : array { global $PAGE; if (empty(static::$contentitems)) { $PAGE->set_context(\context_system::instance()); @@ -86,7 +127,12 @@ class gradeinfo { return static::$contentitems; } - public static function get_contentitem($name) { + /** + * Get specific contentitem (activity icons) by name + * @param mixed $name Name of content item + * @return content_item|null + */ + public static function get_contentitem($name) : ?content_item { $contentitems = static::get_contentitems(); for ($i = 0; $i < count($contentitems); $i++) { if ($contentitems[$i]->get_name() == $name) { @@ -96,7 +142,13 @@ class gradeinfo { return null; } - public static function get_coursecontext_by_id($id) { + /** + * Get a specific course context from grade item id + * @param int $id Grade item id + * @return context_course + * @throws InvalidArgumentException if grade id is not found + */ + public static function get_coursecontext_by_id($id) : \context_course { $gi = grade_item::fetch(["id" => $id]); if (!$gi || course_module_instance_pending_deletion($gi->courseid, $gi->itemmodule, $gi->iteminstance)) { throw new \InvalidArgumentException ("Grade {$id} not found in database"); @@ -104,6 +156,11 @@ class gradeinfo { return \context_course::instance($gi->courseid);; } + /** + * Create new object around a grade_item + * @param int $id Grade item id of the grade item to use as base + * @param studyitem|null $studyitem Studyitem containg the course that references this grade + */ public function __construct($id, studyitem $studyitem = null) { global $DB; $this->studyitem = $studyitem; @@ -157,7 +214,11 @@ class gradeinfo { } - public function is_selected() { + /** + * Check if this gradable item is selected in the studyitem + * @return bool + */ + public function is_selected() : bool { global $DB; if ($this->studyitem) { // Check if selected for this studyitem. @@ -170,6 +231,10 @@ class gradeinfo { return(false); } + /** + * Check if this gradable item is marked required in the studyitem + * @return bool + */ public function is_required() { global $DB; if ($this->studyitem) { @@ -183,6 +248,11 @@ class gradeinfo { return(false); } + /** + * 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'), @@ -199,6 +269,11 @@ class gradeinfo { ], 'referenced course information', $value); } + /** + * Webservice model for editor info + * @param studyitem $studyitem Related studyitem to check for + * @return array Webservice data model + */ public function editor_model(studyitem $studyitem = null) { $model = [ "id" => $this->id, @@ -222,6 +297,11 @@ class gradeinfo { return $model; } + /** + * Webservice structure for user info + * @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'), @@ -240,6 +320,11 @@ class gradeinfo { ], 'referenced 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) { global $DB; $grade = $this->gradeitem->get_final($userid); @@ -282,7 +367,11 @@ class gradeinfo { return $model; } - public function export_model() { + /** + * Export essential information for export + * @return array information model + */ + public function export_model() : array { return [ "name" => $this->name, "type" => $this->gradeitem->itemmodule, @@ -290,6 +379,12 @@ class gradeinfo { "required" => $this->is_required(), ]; } + + /** + * Import data from exported model into database + * @param studyitem $item Studyitem related to this gradable + * @param array $model Model data previously exported + */ public static function import(studyitem $item, array $model) { if ($item->type() == studyitem::COURSE) { $courseid = $item->courseid(); @@ -314,7 +409,13 @@ class gradeinfo { } } - public static function list_course_gradables($course, studyitem $studyitem = null) { + /** + * Get a list if all gradable activities in a given course + * @param \stdClass $course Course database record + * @param studyitem|null $studyitem Studyitem linked to the course which can be linked to created gradeinfo objects + * @return self[] Array of gradeinfo + */ + public static function list_course_gradables($course, studyitem $studyitem = null) : array { $list = []; if (method_exists("\course_modinfo", "get_array_of_activities")) { @@ -352,7 +453,12 @@ class gradeinfo { return $list; } - public static function list_studyitem_gradables(studyitem $studyitem) { + /** + * List all gradables enabled for a given study item + * @param studyitem $studyitem The studyitem to search for + * @return self[] Array of gradeinfo + */ + public static function list_studyitem_gradables(studyitem $studyitem) : array{ global $DB; $table = 'local_treestudyplan_gradeinc'; $list = []; @@ -378,6 +484,16 @@ class gradeinfo { return $list; } + + /** + * Webservice executor to include grade with studyitem or not. + * if both $inclue and $required are false, any existing DB record will be removed + * @param int $gradeid ID of the grade_item + * @param int $itemid ID of the study item + * @param bool $include Select grade_item for studyitem or not + * @param bool $required Mark grade_item as required or not + * @return success Always returns successful success object + */ public static function include_grade(int $gradeid, int $itemid, bool $include, bool $required = false) { global $DB; $table = 'local_treestudyplan_gradeinc'; diff --git a/classes/period.php b/classes/period.php index 671b24e..b6e6586 100644 --- a/classes/period.php +++ b/classes/period.php @@ -26,12 +26,19 @@ defined('MOODLE_INTERNAL') || die(); require_once($CFG->libdir.'/externallib.php'); class period { + /** @var string */ const TABLE = "local_treestudyplan_period"; private static $cache = []; private static $pagecache = []; + /** + * Holds database record + * @var stdClass + */ private $r; // Holds database record. + /** @var int */ private $id; + /** @var studyplanpage */ private $page; public function aggregator() { diff --git a/classes/studyitem.php b/classes/studyitem.php index 75b9436..214ff04 100644 --- a/classes/studyitem.php +++ b/classes/studyitem.php @@ -38,11 +38,18 @@ class studyitem { public const TABLE = "local_treestudyplan_item"; private static $studyitemcache = []; + /** + * Holds database record + * @var stdClass + */ private $r; // Holds database record. + /** @var int */ private $id; private $courseinfo = null; private $studyline; + /** @var aggragator[] */ + /** @var aggragator */ private $aggregator; public function context(): \context { diff --git a/classes/studyitemconnection.php b/classes/studyitemconnection.php index b43655a..5602bcf 100644 --- a/classes/studyitemconnection.php +++ b/classes/studyitemconnection.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 manage connection lines between study items * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -25,18 +25,38 @@ defined('MOODLE_INTERNAL') || die(); require_once($CFG->libdir.'/externallib.php'); +/** + * Class to manage connection lines between study items + */ class studyitemconnection { + /** + * Database table for this model + * @var string */ const TABLE = "local_treestudyplan_connect"; + /** + * Holds database record + * @var stdClass + */ private $r; + /** @var int */ private $id; + /** + * Construct new object based on database object + * @param stdClass $r Database record + */ protected function __construct($r) { $this->r = $r; $this->id = $r->id; } + /** + * Webservice structure for basic info + * @param int $value Webservice requirement constant + * @return external_single_structure Webservice output structure + */ public static function structure($value = VALUE_REQUIRED) { return new \external_single_structure([ 'id' => new \external_value(PARAM_INT, 'id of connection'), @@ -45,27 +65,49 @@ class studyitemconnection { ], '', $value); } + /** + * Webservice model for basic info + * @return array Webservice data model + */ public function model() { return ['id' => $this->r->id, 'from_id' => $this->r->from_id, 'to_id' => $this->r->to_id]; } - public function from_item() { + + /** + * Get originating studyitem for this connection + */ + public function from_item() : studyitem { return studyitem::find_by_id($this->r->from_id); } - public function to_item() { + /** + * Get target studyitem for this connection + */ + public function to_item() : studyitem { return studyitem::find_by_id($this->r->to_id); } - public function from_id() { + /** + * Get originating studyitem id for this connection + */ + public function from_id() : int { return $this->r->from_id; } - public function to_id() { + /** + * Get target studyitem id for this connection + */ + public function to_id() :int { return $this->r->to_id; } - public static function find_outgoing($itemid) { + /** + * Get all connections originating at a given studyitem's id + * @param int $itemid Id of the studyitem + * @return self[] + */ + public static function find_outgoing($itemid) : array { global $DB; $list = []; $connout = $DB->get_records(self::TABLE, ['from_id' => $itemid]); @@ -75,6 +117,11 @@ class studyitemconnection { return $list; } + /** + * Get all connections terminating at a given studyitem's id + * @param int $itemid Id of the studyitem + * @return self[] + */ public static function find_incoming($itemid) { global $DB; $list = []; @@ -85,6 +132,11 @@ class studyitemconnection { return $list; } + /** + * Create a new connection between two study items + * @param int $fromid Id of the originating studyitem + * @param int $toid Id of the target studyitem + */ public static function connect($fromid, $toid) { global $DB; @@ -103,6 +155,11 @@ class studyitemconnection { } } + /** + * Delete a connection between two study items + * @param int $fromid Id of the originating studyitem + * @param int $toid Id of the target studyitem + */ public static function disconnect($fromid, $toid) { global $DB; @@ -118,6 +175,10 @@ class studyitemconnection { } } + /** + * Clear all connection to and from a given studyitem + * @param int $id Id of the studyitem + */ public static function clear($id) { global $DB; $DB->delete_records(self::TABLE, ['from_id' => $id]); diff --git a/classes/studyline.php b/classes/studyline.php index 09ee6b2..a9a3367 100644 --- a/classes/studyline.php +++ b/classes/studyline.php @@ -47,9 +47,16 @@ class studyline { private static $studylinecache = []; + /** + * Holds database record + * @var stdClass + */ private $r; // Holds database record. + /** @var int */ private $id; + /** @var studyplanpage */ private $page; + /** @var studyplan*/ private $studyplan; public function context(): \context { diff --git a/classes/studyplan.php b/classes/studyplan.php index ce91e8f..a80f0bb 100644 --- a/classes/studyplan.php +++ b/classes/studyplan.php @@ -27,14 +27,22 @@ require_once($CFG->libdir.'/externallib.php'); class studyplan { + /** @var string */ const TABLE = "local_treestudyplan"; private static $studyplancache = []; + /** + * Holds database record + * @var stdClass + */ private $r; // Holds database record. + /** @var int */ private $id; + /** @var aggragator */ private $aggregator; private $context = null; // Hold context object once retrieved. private $linkeduserids = null; // Cache lookup of linked users (saves queries). + /** @var studyplanpage[] */ private $pagecache = null; public function aggregator() { diff --git a/classes/studyplanpage.php b/classes/studyplanpage.php index bdfd3db..3ebd899 100644 --- a/classes/studyplanpage.php +++ b/classes/studyplanpage.php @@ -27,11 +27,18 @@ require_once($CFG->libdir.'/externallib.php'); class studyplanpage { + /** @var string */ const TABLE = "local_treestudyplan_page"; private static $cache = []; + /** + * Holds database record + * @var stdClass + */ private $r; // Holds database record. + /** @var int */ private $id; + /** @var studyplan*/ private $studyplan; public function aggregator() { diff --git a/classes/teachingfinder.php b/classes/teachingfinder.php index 2c9e0ba..26bcf0a 100644 --- a/classes/teachingfinder.php +++ b/classes/teachingfinder.php @@ -30,6 +30,7 @@ class teachingfinder { * Table name used for caching teacher info * @var string */ + /** @var string */ const TABLE = "local_treestudyplan_teachers";