From 6f67e5cb84b85bf24f73a1de7321326f4787a4b1 Mon Sep 17 00:00:00 2001 From: PMKuipers Date: Sun, 27 Aug 2023 15:12:54 +0200 Subject: [PATCH] PHPDoc documentation --- build.php | 2 +- cfg_grades.php | 6 +- classes/aggregator.php | 142 +++++++++++++++--- .../local/aggregators/bistate_aggregator.php | 77 +++++++++- classes/local/aggregators/core_aggregator.php | 78 ++++++++-- .../local/aggregators/tristate_aggregator.php | 59 +++++++- classes/local/helpers/webservicehelper.php | 12 +- .../local/ungradedscanners/assign_scanner.php | 26 +++- .../local/ungradedscanners/quiz_scanner.php | 24 ++- .../local/ungradedscanners/scanner_base.php | 25 ++- classes/privacy/provider.php | 34 +++-- classes/studyplan.php | 4 +- classes/success.php | 49 +++++- classes/task/autocohortsync.php | 5 +- classes/task/refreshteacherlist.php | 9 +- cli/prime_students.php | 2 +- cli/randomize_grades.php | 2 +- db/access.php | 2 +- db/services.php | 2 +- db/tasks.php | 2 +- db/upgrade.php | 8 +- doc.php | 2 +- edit-invite.php | 2 +- edit-plan.php | 11 +- invitations.php | 2 +- invited.php | 11 +- lang/en/local_treestudyplan.php | 2 +- lang/nl/local_treestudyplan.php | 2 +- lib.php | 67 ++++----- myreport-embed.php | 12 +- myreport.php | 11 +- settings.php | 8 +- version.php | 2 +- view-plan.php | 11 +- 34 files changed, 586 insertions(+), 127 deletions(-) diff --git a/build.php b/build.php index 8a91c44..c4b147f 100644 --- a/build.php +++ b/build.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Build script to properly create a distribution zip * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/cfg_grades.php b/cfg_grades.php index b9eef5e..f16b69d 100644 --- a/cfg_grades.php +++ b/cfg_grades.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Configure how grades and scales are interpreted by the plugin if no other grade to pass is specified * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -31,6 +31,10 @@ require_capability('local/treestudyplan:configure', $systemcontext); $PAGE->requires->js_call_amd('local_treestudyplan/cfg-grades', 'init'); +/** + * Table name for gradecfg table + * @var string + */ const GRADECFG_TABLE = "local_treestudyplan_gradecfg"; $scales = \grade_scale::fetch_all_global(); diff --git a/classes/aggregator.php b/classes/aggregator.php index 397b56a..2b324a7 100644 --- a/classes/aggregator.php +++ b/classes/aggregator.php @@ -21,25 +21,39 @@ */ namespace local_treestudyplan; +use \ValueError; + defined('MOODLE_INTERNAL') || die(); require_once($CFG->libdir.'/externallib.php'); abstract class aggregator { private const FALLBACK = "bistate"; - private static $modsupported = []; + private static $methodsupported = []; - public static function supported($mod) { - if (!array_key_exists($mod, self::$modsupported)) { - self::$modsupported[$mod] = class_exists(self::aggregator_name($mod)); + /** + * Check if aggregation method is supported + * @param string $method Name of aggregation method + */ + public static function supported($method) { + if (!array_key_exists($method, self::$methodsupported)) { + self::$methodsupported[$method] = class_exists(self::aggregator_name($method)); } - return self::$modsupported[$mod]; + return self::$methodsupported[$method]; } - private static function aggregator_name($mod) { - return "\local_treestudyplan\\local\\aggregators\\{$mod}_aggregator"; + /** + * Get class name for aggregation method + * @param string $method Name of aggregation method + */ + private static function aggregator_name($method) { + return "\local_treestudyplan\\local\\aggregators\\{$method}_aggregator"; } + /** + * Get names of supported aggregation methods + * @return string[] Names of aggregation methods + */ public static function list() { // Static list, since we'd need to implement a lot of static data for new aggregation methods anyway. // And this is faster than any dynamic method. @@ -50,54 +64,131 @@ abstract class aggregator { ]; } - public static function create($mod, $configstr) { - if (self::supported($mod)) { - $agclass = self::aggregator_name($mod); + + /** + * Create a new aggregatior object based on the specified method + * @param mixed $method Aggregation method + * @param mixed $configstr Configuration string for aggregator + * @return self Aggregator + * @throws ValueError If method is not found + */ + public static function create($method, $configstr) { + if (self::supported($method)) { + $agclass = self::aggregator_name($method); return new $agclass($configstr); } else { - throw new \InvalidArgumentException("Cannot find aggregator '{$mod}'"); + throw new \ValueError("Cannot find aggregator '{$method}'"); } } - public static function createordefault($mod, $configstr) { + /** + * Create a new aggregatior object based on the specified method, + * but return a default aggregator if the method is not found + * @param mixed $method Aggregation method + * @param mixed $configstr Configuration string for aggregator + * @return self Aggregator + */ + public static function create_or_default($method, $configstr) { try { - return self::create($mod, $configstr); + return self::create($method, $configstr); } catch (\ValueError $x) { return self::create(self::FALLBACK, ""); } } + /** + * Create new instance of aggregation method + * @param string $configstr Aggregation configuration string + */ private function __construct($configstr) { $this->initialize($configstr); } + /** + * Initialize the aggregation method + * @param string $configstr Aggregation configuration string + */ protected function initialize($configstr) { } + /** + * Determine if aggregation method wants to select gradables + * @return bool True if aggregation method needs gradables to be selected + */ abstract public function select_gradables(); + /** + * Determine if aggregation method is deprecated + * @return bool True if aggregation method is deprecated + */ abstract public function deprecated(); + + /** + * Aggregate all completions in a course into one final course completion + * Possible states: + * completion::EXCELLENT - Completed with excellent results + * completion::GOOD - Completed with good results + * completion::COMPLETED - Completed + * completion::PROGRESS - Started, but not completed yey + * completion::FAILED - Failed + * completion::INCOMPLETE - Not yet started + * @param courseinfo $courseinfo Courseinfo object for the course to check + * @param studyitem $studyitem Studyitem object for the course to check + * @param int $userid Id of user to check this course for + * @return int Aggregated completion as completion class constant + */ abstract public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid); + + /** + * Aggregate juncton/filter inputs into one final junction outcome + * @param int[] $completion List of completion inputs + * @param studyitem $studyitem Studyitem object for the junction + * @param int $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ abstract public function aggregate_junction(array $completion, studyitem $studyitem, $userid); + /** + * Determine completion for a single grade and user + * @param gradeinfo $gradeinfo Gradeinfo object for grade to check + * @param mixed $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ abstract public function grade_completion(gradeinfo $gradeinfo, $userid); - // Aggregation method makes use of "required grades" in a course/module. + /** + * Determine if Aggregation method makes use of "required grades" in a course/module. + * @return bool True if Aggregation method makes use of "required grades" in a course/module. + */ abstract public function use_required_grades(); - // Aggregation method makes use of . + + /** + * Determine if aggregation method makes use of required grades + * @return bool True if aggregation method makes use of + */ abstract public function use_item_conditions(); - // Whether the aggregation method uses core_completion, or treestudyplan custom completion. + /** + * Determine if the aggregation method uses core_completion, or treestudyplan custom completion. + * @return bool True if the aggregation method uses core_completion + */ public function usecorecompletioninfo() { return false; } - // Parameter editing functions - override in child class to implement parameter config for aggregation. - - // Return the current configuration string. + /** + * Return the current configuration string. + * @return string Configuration string + */ public function config_string() { return ""; } + + /** + * Webservice structure for basic aggregator info + * @param int $value Webservice requirement constant + * @return mixed Webservice output structure + */ public static function basic_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ "useRequiredGrades" => new \external_value(PARAM_BOOL, 'id of studyplan'), @@ -105,6 +196,10 @@ abstract class aggregator { ], "Aggregator requirements", $value); } + /** + * Webservice model for basic aggregator info + * @return array Webservice data model + */ public function basic_model() { return [ "useRequiredGrades" => $this->use_required_grades(), @@ -112,6 +207,11 @@ abstract class aggregator { ]; } + /** + * Webservice structure list of aggregators + * @param int $value Webservice requirement constant + * @return mixed Webservice output structure + */ public static function list_structure($value = VALUE_REQUIRED) { return new \external_multiple_structure(new \external_single_structure([ "id" => new \external_value(PARAM_TEXT, 'id of aggregator'), @@ -122,6 +222,10 @@ abstract class aggregator { ], "Available aggregators", $value)); } + /** + * Webservice model for list of aggregators + * @return array Webservice data model + */ public static function list_model() { $list = []; diff --git a/classes/local/aggregators/bistate_aggregator.php b/classes/local/aggregators/bistate_aggregator.php index 78bd75e..2e686e8 100644 --- a/classes/local/aggregators/bistate_aggregator.php +++ b/classes/local/aggregators/bistate_aggregator.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Aggregate course results based on failed/completed states for grades * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -26,13 +26,20 @@ use \local_treestudyplan\courseinfo; use \local_treestudyplan\gradeinfo; use \local_treestudyplan\studyitem; use \local_treestudyplan\completion; -use \local_treestudyplan\debug; +/** + * Aggregate course results based on failed/completed states for grades + */ class bistate_aggregator extends \local_treestudyplan\aggregator { + /** @var bool */ public const DEPRECATED = false; - + /** @var stdClass */ private $agcfg = null; + /** + * Retrieve or initialize current config object + * @return stdClass + */ private function cfg() { if (empty($this->agcfg)) { $this->agcfg = (object)[ @@ -47,11 +54,19 @@ class bistate_aggregator extends \local_treestudyplan\aggregator { return $this->agcfg; } + /** + * Create new instance of aggregation method + * @param string $configstr Aggregation configuration string + */ public function __construct($configstr) { // Allow public constructor for testing purposes. $this->initialize($configstr); } + /** + * Initialize the aggregation method + * @param string $configstr Aggregation configuration string + */ protected function initialize($configstr) { // First initialize with the defaults. @@ -86,7 +101,10 @@ class bistate_aggregator extends \local_treestudyplan\aggregator { } } - // Return active configuration model. + /** + * Return the current configuration string. + * @return string Configuration string + */ public function config_string() { return json_encode([ "thresh_excellent" => 100 * $this->cfg()->thresh_excellent, @@ -98,19 +116,43 @@ class bistate_aggregator extends \local_treestudyplan\aggregator { ]); } + /** + * Determine if aggregation method wants to select gradables + * @return bool True if aggregation method needs gradables to be selected + */ public function select_gradables() { return true; } + /** + * Determine if aggregation method is deprecated + * @return bool True if aggregation method is deprecated + */ public function deprecated() { return self::DEPRECATED; } + + /** + * Determine if Aggregation method makes use of "required grades" in a course/module. + * @return bool True if Aggregation method makes use of "required grades" in a course/module. + */ public function use_required_grades() { return true; } + + /** + * Determine if aggregation method makes use of required grades + * @return bool True if aggregation method makes use of + */ public function use_item_conditions() { return false; } + /** + * Aggregate completed/failed goals into one outcome + * @param int[] $completions List of completions (completion class constants) + * @param array $required List of completions indexes that are marked as required + * @return int Aggregated completion as completion class constant + */ public function aggregate_binary_goals(array $completions, array $required = []) { // Function is public to allow access for the testing code. @@ -164,6 +206,20 @@ class bistate_aggregator extends \local_treestudyplan\aggregator { } } + /** + * Aggregate all completions in a course into one final course completion + * Possible states: + * completion::EXCELLENT - Completed with excellent results + * completion::GOOD - Completed with good results + * completion::COMPLETED - Completed + * completion::PROGRESS - Started, but not completed yey + * completion::FAILED - Failed + * completion::INCOMPLETE - Not yet started + * @param courseinfo $courseinfo Courseinfo object for the course to check + * @param studyitem $studyitem Studyitem object for the course to check + * @param int $userid Id of user to check this course for + * @return int Aggregated completion as completion class constant + */ public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid) { $course = $courseinfo->course(); $coursefinished = ($course->enddate) ? ($course->enddate < time()) : false; @@ -190,6 +246,13 @@ class bistate_aggregator extends \local_treestudyplan\aggregator { } + /** + * Aggregate juncton/filter inputs into one final junction outcome + * @param int[] $completion List of completion inputs + * @param studyitem $studyitem Studyitem object for the junction + * @param int $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ public function aggregate_junction(array $completion, studyitem $studyitem = null, $userid = 0) { // Aggregate multiple incoming states into one junction or finish. // Possible states:. @@ -222,6 +285,12 @@ class bistate_aggregator extends \local_treestudyplan\aggregator { } } + /** + * Determine completion for a single grade and user + * @param gradeinfo $gradeinfo Gradeinfo object for grade to check + * @param mixed $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ public function grade_completion(gradeinfo $gradeinfo, $userid) { global $DB; $table = "local_treestudyplan_gradecfg"; diff --git a/classes/local/aggregators/core_aggregator.php b/classes/local/aggregators/core_aggregator.php index 3b135e8..f87f393 100644 --- a/classes/local/aggregators/core_aggregator.php +++ b/classes/local/aggregators/core_aggregator.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Aggregate course results with moodle course completion * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -27,12 +27,20 @@ use \local_treestudyplan\corecompletioninfo; use \local_treestudyplan\gradeinfo; use \local_treestudyplan\studyitem; use \local_treestudyplan\completion; -use \local_treestudyplan\debug; +/** + * Aggregate course results with moodle course completion + */ class core_aggregator extends \local_treestudyplan\aggregator { + /** @var bool */ public const DEPRECATED = false; + /** @var array */ private $agcfg = null; + /** + * Retrieve or initialize current config object + * @return stdClass + */ private function cfg() { if (empty($this->agcfg)) { $this->agcfg = (object)[ @@ -42,11 +50,19 @@ class core_aggregator extends \local_treestudyplan\aggregator { return $this->agcfg; } + /** + * Create new instance of aggregation method + * @param string $configstr Aggregation configuration string + */ public function __construct($configstr) { // Allow public constructor for testing purposes. $this->initialize($configstr); } + /** + * Initialize the aggregation method + * @param string $configstr Aggregation configuration string + */ protected function initialize($configstr) { // First initialize with the defaults. foreach (["accept_pending_as_submitted"] as $key) { @@ -66,25 +82,52 @@ class core_aggregator extends \local_treestudyplan\aggregator { } } - // Return active configuration model. + /** + * Return the current configuration string. + * @return string Configuration string + */ public function config_string() { return json_encode([ "accept_pending_as_submitted" => $this->cfg()->accept_pending_as_submitted, ]); } + /** + * Determine if aggregation method wants to select gradables + * @return bool True if aggregation method needs gradables to be selected + */ public function select_gradables() { return false; } + + /** + * Determine if aggregation method is deprecated + * @return bool True if aggregation method is deprecated + */ public function deprecated() { return self::DEPRECATED; } + + /** + * Determine if Aggregation method makes use of "required grades" in a course/module. + * @return bool True if Aggregation method makes use of "required grades" in a course/module. + */ public function use_required_grades() { return true; } + + /** + * Determine if aggregation method makes use of required grades + * @return bool True if aggregation method makes use of + */ public function use_item_conditions() { return false; } + + /** + * Determine if the aggregation method uses core_completion, or treestudyplan custom completion. + * @return bool True if the aggregation method uses core_completion + */ public function usecorecompletioninfo() { return true; } @@ -98,13 +141,11 @@ class core_aggregator extends \local_treestudyplan\aggregator { * completion::PROGRESS - Started, but not completed yey * completion::FAILED - Failed * completion::INCOMPLETE - Not yet started - * - * @param mixed $courseinfo - * @param mixed $studyitem - * @param mixed $userid - * @return void + * @param courseinfo $courseinfo Courseinfo object for the course to check + * @param studyitem $studyitem Studyitem object for the course to check + * @param int $userid Id of user to check this course for + * @return int Aggregated completion as completion class constant */ - public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid) { // Retrieve the core completion info from the core. $course = $courseinfo->course(); @@ -145,6 +186,13 @@ class core_aggregator extends \local_treestudyplan\aggregator { } } + /** + * Aggregate juncton/filter inputs into one final junction outcome + * @param int[] $completion List of completion inputs + * @param studyitem $studyitem Studyitem object for the junction + * @param int $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ public function aggregate_junction(array $completion, studyitem $studyitem = null, $userid = 0) { // Aggregate multiple incoming states into one junction or finish. // Possible states:. @@ -177,10 +225,16 @@ class core_aggregator extends \local_treestudyplan\aggregator { } } - // CORE COMPLETION DOESN'T REALLY USE THE FUNCTIONS BELOW. - // AGGREGATORS ARE GOING TO BE DEPRECATED ANYWAY... but used in legacy parts of this plugin. - + + /** + * Determine completion for a single grade and user + * @param gradeinfo $gradeinfo Gradeinfo object for grade to check + * @param mixed $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ public function grade_completion(gradeinfo $gradeinfo, $userid) { + // CORE COMPLETION DOESN'T REALLY USE THIS FUNCTION + global $DB; $table = "local_treestudyplan_gradecfg"; $gradeitem = $gradeinfo->get_gradeitem(); diff --git a/classes/local/aggregators/tristate_aggregator.php b/classes/local/aggregators/tristate_aggregator.php index 7795474..1cc81da 100644 --- a/classes/local/aggregators/tristate_aggregator.php +++ b/classes/local/aggregators/tristate_aggregator.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Aggregate course results based on failed, completed, excellent states for grades * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -27,23 +27,53 @@ use \local_treestudyplan\gradeinfo; use \local_treestudyplan\studyitem; use \local_treestudyplan\completion; +/** + * Aggregate course results based on failed, achieved, completed states for grades + * @deprecated This aggregation style is no longer used, but included to support old study plans + */ class tristate_aggregator extends \local_treestudyplan\aggregator { + /** @var bool */ public const DEPRECATED = true; + /** @var string */ private const DEFAULT_CONDITION = "50"; + /** + * Determine if aggregation method wants to select gradables + * @return bool True if aggregation method needs gradables to be selected + */ public function select_gradables() { return true; } + /** + * Determine if aggregation method is deprecated + * @return bool True if aggregation method is deprecated + */ public function deprecated() { return self::DEPRECATED; } + + /** + * Determine if Aggregation method makes use of "required grades" in a course/module. + * @return bool True if Aggregation method makes use of "required grades" in a course/module. + */ public function use_required_grades() { return false; } + + /** + * Determine if aggregation method makes use of required grades + * @return bool True if aggregation method makes use of + */ public function use_item_conditions() { return true; } + /** + * Aggregate completions into final result + * @param int[] $a List of completion inputs + * @param string $condition Condition description [ALL, 67, 50, ANY] + * @return int Aggregated completion as completion class constant + */ protected function aggregate_completion(array $a, $condition = "50") { if (in_array($condition, ['ALL', '67', '50', 'ANY'])) { // Condition is one of the valid conditions. @@ -95,6 +125,20 @@ class tristate_aggregator extends \local_treestudyplan\aggregator { } } + /** + * Aggregate all completions in a course into one final course completion + * Possible states: + * completion::EXCELLENT - Completed with excellent results + * completion::GOOD - Completed with good results + * completion::COMPLETED - Completed + * completion::PROGRESS - Started, but not completed yey + * completion::FAILED - Failed + * completion::INCOMPLETE - Not yet started + * @param courseinfo $courseinfo Courseinfo object for the course to check + * @param studyitem $studyitem Studyitem object for the course to check + * @param int $userid Id of user to check this course for + * @return int Aggregated completion as completion class constant + */ public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid) { $condition = $studyitem->conditions(); if (empty($condition)) { @@ -108,12 +152,25 @@ class tristate_aggregator extends \local_treestudyplan\aggregator { return $completion; } + /** + * Aggregate juncton/filter inputs into one final junction outcome + * @param int[] $completion List of completion inputs + * @param studyitem $studyitem Studyitem object for the junction + * @param int $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ public function aggregate_junction(array $completion, studyitem $studyitem, $userid) { $completed = self::aggregate_completion($completion, $studyitem->conditions()); // If null result (conditions are unknown/null) - default to ALL. return isset($completed) ? $completed : (self::aggregate_completion($completion, 'ALL')); } + /** + * Determine completion for a single grade and user + * @param gradeinfo $gradeinfo Gradeinfo object for grade to check + * @param mixed $userid Id of user to check completion for + * @return int Aggregated completion as completion class constant + */ public function grade_completion(gradeinfo $gradeinfo, $userid) { global $DB; $gradeitem = $gradeinfo->get_gradeitem(); diff --git a/classes/local/helpers/webservicehelper.php b/classes/local/helpers/webservicehelper.php index c67a61e..f3577f4 100644 --- a/classes/local/helpers/webservicehelper.php +++ b/classes/local/helpers/webservicehelper.php @@ -14,19 +14,25 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Helper functions for web services * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ namespace local_treestudyplan\local\helpers; +use \core_course_category; + defined('MOODLE_INTERNAL') || die(); require_once($CFG->dirroot.'/webservice/lib.php'); +/** + * Class containing helper functions for webservices + */ class webservicehelper { /** @var \context_system */ private static $systemcontext = null; + /** @var \context[] */ private static $validatedcontexts = []; /** @@ -58,10 +64,10 @@ class webservicehelper { /** * Test if the current user has a certain capability in any of the categories they have access to * @param string $capability The capability to scan for in the categories - * @param \core_course_category $parent The parent category to use as a scanning base. Used internally. + * @param core_course_category $parent The parent category to use as a scanning base. Used internally. * @return boolean */ - public static function has_capability_in_any_category($capability, \core_course_category $parent = null) { + public static function has_capability_in_any_category($capability, core_course_category $parent = null) { // List the categories in which the user has a specific capability. $list = []; diff --git a/classes/local/ungradedscanners/assign_scanner.php b/classes/local/ungradedscanners/assign_scanner.php index 5295301..b1307eb 100644 --- a/classes/local/ungradedscanners/assign_scanner.php +++ b/classes/local/ungradedscanners/assign_scanner.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Scan submissions in assign activities * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -22,8 +22,14 @@ namespace local_treestudyplan\local\ungradedscanners; +/** + * Activity scanner for assignment activity + */ class assign_scanner extends scanner_base { + /** + * Retrieve the ungraded submissions in this activity + */ protected function get_ungraded_submissions() { global $DB; $sql = "SELECT DISTINCT asgn_sub.userid @@ -40,6 +46,9 @@ class assign_scanner extends scanner_base { return $DB->get_fieldset_sql($sql, ['iteminstance' => $this->gi->iteminstance]); } + /** + * Get the users with graded results + */ protected function get_graded_users() { global $DB; $sql = "SELECT DISTINCT g.userid @@ -50,6 +59,11 @@ class assign_scanner extends scanner_base { return $DB->get_fieldset_sql($sql, ['iteminstance' => $this->gi->iteminstance]); } + /** + * Count the number of students wit ungraded submissions in this activity + * @param array $courseuserids + * @return int Number of students with ungraded submissions + */ public function count_ungraded($courseuserids = []) { $ungraded = $this->get_ungraded_submissions(); @@ -59,6 +73,11 @@ class assign_scanner extends scanner_base { return count($ungraded); } + /** + * Count the number of students wit (all) graded submissions in this activity + * @param array $courseuserids + * @return int Number of students with graded submission + */ public function count_graded($courseuserids = []) { $ungraded = $this->get_ungraded_submissions(); $graded = $this->get_graded_users(); @@ -74,6 +93,11 @@ class assign_scanner extends scanner_base { return count($graded) - count($dual); } + /** + * Check if specified user has ungraded submission in this activity + * @param mixed $userid User id of user to check + * @return bool If specified user has ungraded submissions in this activity + */ public function has_ungraded_submission($userid) { $ungraded = $this->get_ungraded_submissions(); return in_array($userid, $ungraded); diff --git a/classes/local/ungradedscanners/quiz_scanner.php b/classes/local/ungradedscanners/quiz_scanner.php index 5fa641b..9af3cf5 100644 --- a/classes/local/ungradedscanners/quiz_scanner.php +++ b/classes/local/ungradedscanners/quiz_scanner.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Scan submissions in assign activities * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -25,8 +25,13 @@ namespace local_treestudyplan\local\ungradedscanners; defined('MOODLE_INTERNAL') || die(); require_once($CFG->dirroot.'/question/engine/states.php'); // For reading question state. +/** + * Activity scanner for quiz activity + */ class quiz_scanner extends scanner_base { - + /** + * Retrieve the ungraded submissions in this activity + */ protected function get_ungraded_submissions() { // Count all users who have one or more questions that still need grading. global $DB; @@ -55,6 +60,11 @@ class quiz_scanner extends scanner_base { return array_keys($submissions); } + /** + * Count the number of students wit ungraded submissions in this activity + * @param array $courseuserids + * @return int Number of students with ungraded submissions + */ public function count_ungraded($courseuserids = []) { $ungraded = $this->get_ungraded_submissions(); if (count($courseuserids) > 0) { @@ -63,6 +73,11 @@ class quiz_scanner extends scanner_base { return count($ungraded); } + /** + * Count the number of students wit (all) graded submissions in this activity + * @param array $courseuserids + * @return int Number of students with graded submission + */ public function count_graded($courseuserids = []) { // Count all users who submitted one or more finished tests. global $DB; @@ -81,6 +96,11 @@ class quiz_scanner extends scanner_base { return count($graded); } + /** + * Check if specified user has ungraded submission in this activity + * @param mixed $userid User id of user to check + * @return bool If specified user has ungraded submissions in this activity + */ public function has_ungraded_submission($userid) { $ungraded = $this->get_ungraded_submissions(); return in_array($userid, $ungraded); diff --git a/classes/local/ungradedscanners/scanner_base.php b/classes/local/ungradedscanners/scanner_base.php index eb1b7d7..409013a 100644 --- a/classes/local/ungradedscanners/scanner_base.php +++ b/classes/local/ungradedscanners/scanner_base.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Base class to scan submissions in activities * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -24,17 +24,40 @@ namespace local_treestudyplan\local\ungradedscanners; use \grade_item; +/** + * Base class for activity scanners + */ abstract class scanner_base { + /** @var grade_item */ protected $gi; + /** + * Create new object based on grade_item + * @param grade_item $gi The grade item for this activity + */ public function __construct(grade_item $gi) { $this->gi = $gi; } + /** + * Count the number of students wit ungraded submissions in this activity + * @param array $courseuserids + * @return int Number of students with ungraded submissions + */ abstract public function count_ungraded($courseuserids = []); + /** + * Count the number of students wit (all) graded submissions in this activity + * @param array $courseuserids + * @return int Number of students with graded submission + */ abstract public function count_graded($courseuserids = []); + /** + * Check if specified user has ungraded submission in this activity + * @param mixed $userid User id of user to check + * @return bool If specified user has ungraded submissions in this activity + */ abstract public function has_ungraded_submission($userid); } diff --git a/classes/privacy/provider.php b/classes/privacy/provider.php index 51dc7ac..a163c56 100644 --- a/classes/privacy/provider.php +++ b/classes/privacy/provider.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Privacy information metadata * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -22,17 +22,21 @@ namespace local_treestudyplan\privacy; -use core_privacy\local\metadata\collection; +use \core_privacy\local\metadata\collection; use \core_privacy\local\request\userlist; -use core_privacy\local\request\contextlist; +use \core_privacy\local\request\contextlist; use \core_privacy\local\request\approved_contextlist; use \core_privacy\local\request\approved_userlist; use \core_privacy\local\request\deletion_criteria; use \core_privacy\local\request\writer; use \core_privacy\local\request\helper; use \core_privacy\local\request\transform; -use tool_dataprivacy\context_instance; +use \tool_dataprivacy\context_instance; +use \context; +/** + * Privacy provider + */ class provider implements \core_privacy\local\metadata\provider, \core_privacy\local\request\plugin\provider, \core_privacy\local\request\core_userlist_provider { @@ -46,6 +50,11 @@ class provider implements \core_privacy\local\metadata\provider, return 'privacy:metadata'; } + /** + * Get metadata about collected personal data + * @param collection $collection + * @return collection + */ public static function get_metadata(collection $collection): collection { $collection->add_database_table( @@ -71,7 +80,6 @@ class provider implements \core_privacy\local\metadata\provider, /** * Get the list of contexts that contain user information for the specified user. - * * @param int $userid The user to search. * @return contextlist $contextlist The contextlist containing the list of contexts used in this plugin. */ @@ -91,7 +99,6 @@ class provider implements \core_privacy\local\metadata\provider, /** * Export all user data for the specified user, in the specified contexts. - * * @param approved_contextlist $contextlist The approved contexts to export information for. */ public static function export_user_data(approved_contextlist $contextlist) { @@ -134,8 +141,7 @@ class provider implements \core_privacy\local\metadata\provider, /** * Export the supplied personal data for an invitation. - * - * @param $invit The invitation record. + * @param stdClass $invit The invitation record. */ protected static function export_invitation_data_for_user($invit) { $context = \context_system::instance(); @@ -147,9 +153,8 @@ class provider implements \core_privacy\local\metadata\provider, } /** - * Export the supplied personal data for an invitation. - * - * @param $invit The invitation record. + * Export studyplan data for (current) user + * @param stdClass $studyplan The studyplan */ protected static function export_studyplan_data_for_user($studyplan) { $context = \context_system::instance(); @@ -163,10 +168,9 @@ class provider implements \core_privacy\local\metadata\provider, /** * Delete all data for all users in the specified context. * Used when a context is past it's data retention period - * - * @param context $context The specific context to delete data for. + * @param context $context The specific context to delete data for. */ - public static function delete_data_for_all_users_in_context(\context $context) { + public static function delete_data_for_all_users_in_context(context $context) { global $DB; // Find studyplans in context. if ($context->contextlevel == CONTEXT_COURSECAT) { @@ -218,7 +222,6 @@ class provider implements \core_privacy\local\metadata\provider, /** * Get the list of users who have data within a context. - * * @param userlist $userlist The userlist containing the list of users who have data in this context/plugin combination. */ public static function get_users_in_context(userlist $userlist) { @@ -250,7 +253,6 @@ class provider implements \core_privacy\local\metadata\provider, /** * Delete multiple users within a single context. - * * @param approved_userlist $userlist The approved context and user information to delete information for. */ public static function delete_data_for_users(approved_userlist $userlist) { diff --git a/classes/studyplan.php b/classes/studyplan.php index 1a91b78..ce91e8f 100644 --- a/classes/studyplan.php +++ b/classes/studyplan.php @@ -54,7 +54,7 @@ class studyplan { $this->id = $id; $this->r = $DB->get_record(self::TABLE, ['id' => $id]); - $this->aggregator = aggregator::createordefault($this->r->aggregation, $this->r->aggregation_config); + $this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config); } public function id() { @@ -250,7 +250,7 @@ class studyplan { $this->context = null; $this->context(); // Reload aggregator. - $this->aggregator = aggregator::createordefault($this->r->aggregation, $this->r->aggregation_config); + $this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config); // Start temporary skräpp code. // TODO: Until proper page editing is implemented, copy data from studyplan to it's first page. diff --git a/classes/success.php b/classes/success.php index b0bb4b1..0025234 100644 --- a/classes/success.php +++ b/classes/success.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Webservice return value to describe a single event as successful or not * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -22,23 +22,54 @@ namespace local_treestudyplan; +/** + * Describes a webservice result a successful or not with optional message + */ class success { + + /** + * Success (true) or failed (false) + * @var bool + */ private $success; + /** + * Messsage passed with result + * @var string + */ private $msg; + /** + * Create new successful result with optional message + * @param string $msg Message to add to result + * @return self Succesful success object + */ public static function success($msg = "") { return new self(true, $msg); } + /** + * Create new failed result with optional message + * @param string $msg Message to add to result + * @return self Failed success object + */ public static function fail($msg = "") { return new self(false, $msg); } + /** + * Create new succes result + * @param bool $success Whether result is succesful or not + * @param string $msg Message to add to result + */ public function __construct($success, $msg) { $this->success = ($success) ? true : false; $this->msg = $msg; } + /** + * Describe the result for the + * @return external_single_structure + */ public static function structure() { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), @@ -46,14 +77,30 @@ class success { ]); } + + /** + * Make the webservice result model + * + * @return array Webservice value + */ public function model() { return ["success" => $this->success, "msg" => $this->msg]; } + /** + * Get success status of object + * + * @return bool If this success is successful or not + */ public function successful() { return $this->success; } + /** + * Get message + * + * @return string Message + */ public function msg() { return $this->msg; } diff --git a/classes/task/autocohortsync.php b/classes/task/autocohortsync.php index ab4166e..3a4bfd1 100644 --- a/classes/task/autocohortsync.php +++ b/classes/task/autocohortsync.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Task to autosync studyplan associated cohorts and users with the courses in the studyplan * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -28,6 +28,9 @@ use local_treestudyplan\studyplan; use local_treestudyplan\cascadecohortsync; use local_treestudyplan\cascadeusersync; +/** + * Task to enrol users and cohorts associated with a studyplan in all courses linked in that studyplan + */ class autocohortsync extends \core\task\scheduled_task { /** diff --git a/classes/task/refreshteacherlist.php b/classes/task/refreshteacherlist.php index 9a42287..68e7587 100644 --- a/classes/task/refreshteacherlist.php +++ b/classes/task/refreshteacherlist.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Background task to refresh the list of associaded teachers with studyplans * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -26,7 +26,14 @@ defined('MOODLE_INTERNAL') || die(); require_once($CFG->dirroot.'/course/externallib.php'); use local_treestudyplan\teachingfinder; +/** + * Background task to refresh the list of associaded teachers with studyplans + */ class refreshteacherlist extends \core\task\scheduled_task { + /** + * Maximum time a result is valid before refreshing + * @var int + */ const CACHE_TIME = 4 * 60 * 60; // 2 hours. /** diff --git a/cli/prime_students.php b/cli/prime_students.php index 361bfbc..a869a63 100644 --- a/cli/prime_students.php +++ b/cli/prime_students.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Developer CLI tool. Primes grade generator with random student properties * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/cli/randomize_grades.php b/cli/randomize_grades.php index 27f3ce7..9ccc1eb 100644 --- a/cli/randomize_grades.php +++ b/cli/randomize_grades.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * +* Developer CLI tool. Fill all the gradables in a study plan with random values * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/db/access.php b/db/access.php index 830d600..249d88c 100644 --- a/db/access.php +++ b/db/access.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Describes roles and permissions * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/db/services.php b/db/services.php index 145b96d..c5024c1 100644 --- a/db/services.php +++ b/db/services.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Webservice function register * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/db/tasks.php b/db/tasks.php index bc26053..117843d 100644 --- a/db/tasks.php +++ b/db/tasks.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Background task register * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/db/upgrade.php b/db/upgrade.php index 4dff8bd..0fb2e2f 100644 --- a/db/upgrade.php +++ b/db/upgrade.php @@ -14,12 +14,18 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Database upgrade script * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ +/** + * Hook to upgrade database upon plugin upgrade + * @param mixed $oldversion Version of plugin database before upgrade + * @return bool Upgrade success status + * + */ function xmldb_local_treestudyplan_upgrade($oldversion) { global $DB; $dbman = $DB->get_manager(); diff --git a/doc.php b/doc.php index 05e6a70..0a3073e 100644 --- a/doc.php +++ b/doc.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Documentation renderer * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/edit-invite.php b/edit-invite.php index c6fc2af..2da64b0 100644 --- a/edit-invite.php +++ b/edit-invite.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Edit an existing or new invitation to view a studyplan * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/edit-plan.php b/edit-plan.php index 1906ef6..c037d3e 100644 --- a/edit-plan.php +++ b/edit-plan.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Edit/manage study plans * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -80,7 +80,14 @@ $PAGE->requires->js_call_amd('local_treestudyplan/page-edit-plan', 'init', [$stu $catlist = courseservice::list_accessible_categories_with_usage("edit"); - // Local translate function. +/** + * Shortcut function to provide translations + * + * @param mixed $str Translation key + * @param null|string[] $param Parameters to pass to translation + * @param string $plugin Location to search for translation strings + * @return string Translation of key + */ function t($str, $param = null, $plugin = 'local_treestudyplan') { print get_string($str, $plugin, $param); } diff --git a/invitations.php b/invitations.php index 58a12e1..7269f09 100644 --- a/invitations.php +++ b/invitations.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Entry point for students to manage invitations to view their study plan * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/invited.php b/invited.php index d521ce9..15eff5d 100644 --- a/invited.php +++ b/invited.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Entry point for external people to access a studyplan view with an invitation * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -23,7 +23,14 @@ require_once("../../config.php"); // Since this page is externally accessed and validated in a different way, no login is needed. -// Local translate function. +/** + * Shortcut function to provide translations + * + * @param mixed $str Translation key + * @param null|string[] $param Parameters to pass to translation + * @param string $plugin Location to search for translation strings + * @return string Translation of key + */ function t($str, $param = null, $plugin = 'local_treestudyplan') { print get_string($str, $plugin, $param); } diff --git a/lang/en/local_treestudyplan.php b/lang/en/local_treestudyplan.php index 6a4e4f1..5c7667e 100644 --- a/lang/en/local_treestudyplan.php +++ b/lang/en/local_treestudyplan.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * English language file * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/lang/nl/local_treestudyplan.php b/lang/nl/local_treestudyplan.php index df506e5..69bd5b8 100644 --- a/lang/nl/local_treestudyplan.php +++ b/lang/nl/local_treestudyplan.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Dutch language file * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/lib.php b/lib.php index 4eff302..07cd3a0 100644 --- a/lib.php +++ b/lib.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Moodle hook functions and some internally used functions * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -26,7 +26,12 @@ use local_treestudyplan\local\helpers\webservicehelper; use \local_treestudyplan\studyplan; -function local_treestudyplan_unit_get_editor_options($context) { +/** + * Describe editor options + * @param context $context Context for options + * @return array Editor options + */ +function local_treestudyplan_unit_get_editor_options(context $context) { global $CFG; return ['subdirs' => 1, 'maxbytes' => $CFG->maxbytes, @@ -37,6 +42,10 @@ function local_treestudyplan_unit_get_editor_options($context) { 'trusttext' => 0]; } +/** + * Hook to extend navigation + * @param global_navigation $navigation Navigation object + */ function local_treestudyplan_extend_navigation(global_navigation $navigation) { global $CFG, $PAGE, $COURSE, $USER; @@ -148,6 +157,11 @@ function local_treestudyplan_extend_navigation(global_navigation $navigation) { } +/** + * Hook to extend navigation in category view + * @param mixed $navigation + * @param context_coursecat $coursecategorycontext + */ function local_treestudyplan_extend_navigation_category_settings($navigation, context_coursecat $coursecategorycontext) { global $CFG, $PAGE; $categoryid = $coursecategorycontext->instanceid; @@ -176,6 +190,11 @@ function local_treestudyplan_extend_navigation_category_settings($navigation, co } +/** + * Map fontawesome icons for use in flat navigation + * @return array Icon mapping + * + */ function local_treestudyplan_get_fontawesome_icon_map() { // Create the icon map with the icons which are used in any case. @@ -184,9 +203,9 @@ function local_treestudyplan_get_fontawesome_icon_map() { 'local_treestudyplan:editplans' => 'fa-share-alt', 'local_treestudyplan:viewplans' => 'fa-share-alt', ]; - return $iconmapping; } + /** * Helper function to reset the icon system used as updatecallback function when saving some of the plugin's settings. */ @@ -201,6 +220,11 @@ function local_treestudyplan_reset_fontawesome_icon_map() { $instance->get_icon_name_map(); } +/** + * Send invitation to invited person + * @param mixed $inviteid Database id of the invitation + * + */ function local_treestudyplan_send_invite($inviteid) { global $DB, $USER, $CFG; $invite = $DB->get_record("local_treestudyplan_invit", array('id' => $inviteid)); @@ -259,38 +283,11 @@ function local_treestudyplan_send_invite($inviteid) { } -function local_treestudyplan_find_cohortmembers($cohortid) { - global $DB; - // By default wherecondition retrieves all users except the deleted, not confirmed and guest. - $params = ['cohortid' => $cohortid]; - $sql = "SELECT * FROM {user} u - JOIN {cohort_members} cm ON (cm.userid = u.id AND cm.cohortid = :cohortid) - WHERE u.suspended = 0 AND u.id > 1 - ORDER BY u.lastname - "; - $availableusers = $DB->get_records_sql($sql, $params); - return $availableusers; -} - -function local_treestudyplan_get_cohort_path($cohort) { - $cohortcontext = context::instance_by_id($cohort->contextid); - if ($cohortcontext && $cohortcontext->id != SYSCONTEXTID) { - $ctxpath = array_map( - function($ctx) { - return $ctx->get_context_name(false); - }, - $cohortcontext->get_parent_contexts(true) - ); - array_pop($ctxpath); // Pop system context off the list. - $ctxpath = array_reverse($ctxpath); - $ctxpath[] = $cohort->name; - - return implode(" / ", $ctxpath); - } else { - return $cohort->name; - } -} - +/** + * Hook to display fragment of activity/mod settings editor. Used in feature to edit name and description of activity + * @param mixed $args + * @return string Rendered form output HTML + */ function local_treestudyplan_output_fragment_mod_edit_form($args) { global $CFG; global $DB; diff --git a/myreport-embed.php b/myreport-embed.php index 1e6bbf7..13c3000 100644 --- a/myreport-embed.php +++ b/myreport-embed.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Entry point for other moodle modules to embed the user's report in a view * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -41,7 +41,15 @@ $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/boot $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/devstyles.css')); $PAGE->requires->js_call_amd('local_treestudyplan/page-myreport', 'init'); - // Local translate function. + +/** + * Shortcut function to provide translations + * + * @param mixed $str Translation key + * @param null|string[] $param Parameters to pass to translation + * @param string $plugin Location to search for translation strings + * @return string Translation of key + */ function t($str, $param = null, $plugin = 'local_treestudyplan') { print get_string($str, $plugin, $param); } diff --git a/myreport.php b/myreport.php index 3024c81..c321410 100644 --- a/myreport.php +++ b/myreport.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Show student's studyplans in a report overview * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -49,7 +49,14 @@ $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/boot $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/devstyles.css')); $PAGE->requires->js_call_amd('local_treestudyplan/page-myreport', 'init', [$teachermode ? 'teaching' : 'myreport']); - // Local translate function. +/** + * Shortcut function to provide translations + * + * @param mixed $str Translation key + * @param null|string[] $param Parameters to pass to translation + * @param string $plugin Location to search for translation strings + * @return string Translation of key + */ function t($str, $param = null, $plugin = 'local_treestudyplan') { print get_string($str, $plugin, $param); } diff --git a/settings.php b/settings.php index d0c9856..17903e1 100644 --- a/settings.php +++ b/settings.php @@ -15,11 +15,11 @@ // along with Moodle. If not, see . /** - * Local plugin "Boost navigation fumbling" - Settings + * Local plugin Settings * - * @package local_chronotable - * @copyright 2017 Alexander Bias, Ulm University - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later. + * @package local_treestudyplan + * @copyright 2023 P.M. Kuipers + * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); diff --git a/version.php b/version.php index 50e400d..ef53fca 100644 --- a/version.php +++ b/version.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Plugin version * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later diff --git a/view-plan.php b/view-plan.php index 23488c9..57b7097 100644 --- a/view-plan.php +++ b/view-plan.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * View study plans - teacher view and student view * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -78,7 +78,14 @@ $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/boot $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/devstyles.css')); $PAGE->requires->js_call_amd('local_treestudyplan/page-view-plan', 'init', [$studyplancontext->id, $categoryid]); - // Local translate function. +/** + * Shortcut function to provide translations + * + * @param mixed $str Translation key + * @param null|string[] $param Parameters to pass to translation + * @param string $plugin Location to search for translation strings + * @return string Translation of key + */ function t($str, $param = null, $plugin = 'local_treestudyplan') { print get_string($str, $plugin, $param); }