From f0e37669575ee7989823571eb76c7e0f7b678a96 Mon Sep 17 00:00:00 2001 From: PMKuipers Date: Sun, 27 Aug 2023 17:00:23 +0200 Subject: [PATCH] PHPDoc documentation --- classes/aggregator.php | 13 +++-- classes/cascadecohortsync.php | 30 ++++++++++- classes/cascadeusersync.php | 18 ++++++- classes/contextinfo.php | 35 +++++++++++-- classes/local/gradegenerator.php | 87 ++++++++++++++++++++++++++++++-- classes/reportinvite_form.php | 20 +++++++- classes/success.php | 3 +- classes/teachingfinder.php | 28 ++++++++-- 8 files changed, 213 insertions(+), 21 deletions(-) diff --git a/classes/aggregator.php b/classes/aggregator.php index 2b324a7..f759108 100644 --- a/classes/aggregator.php +++ b/classes/aggregator.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 for aggregators * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -27,8 +27,15 @@ defined('MOODLE_INTERNAL') || die(); require_once($CFG->libdir.'/externallib.php'); +/** + * Base class for aggregators + */ abstract class aggregator { - private const FALLBACK = "bistate"; + /** Fallback aggregator if method not found + * @var string + * */ + private const FALLBACK = "core"; + /** @var string[] */ private static $methodsupported = []; /** @@ -187,7 +194,7 @@ abstract class aggregator { /** * Webservice structure for basic aggregator info * @param int $value Webservice requirement constant - * @return mixed Webservice output structure + * @return external_single_structure Webservice output structure */ public static function basic_structure($value = VALUE_REQUIRED) { return new \external_single_structure([ diff --git a/classes/cascadecohortsync.php b/classes/cascadecohortsync.php index 61e6dfd..a523fad 100644 --- a/classes/cascadecohortsync.php +++ b/classes/cascadecohortsync.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Synchronize enrolled cohorts in courses with cohorts associated with studyplans these courses are in * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -27,16 +27,34 @@ require_once($CFG->libdir.'/externallib.php'); use \local_treestudyplan\studyplan; +/** + * Task class to synchronize enrolled cohorts in courses with cohorts associated with studyplans these courses are in + */ class cascadecohortsync { + /** Method to use for 'enrolment' + * @var string + */ private const METHOD = "cohort"; + /** @var studyplan */ private $studyplan; + /** @var int */ private $studyplanid; + /** + * Create a synchronization task for a studyplan + * @param studyplan $studyplan The studyplan to enrol students for + */ public function __construct(studyplan $studyplan) { $this->studyplan = $studyplan; $this->studyplanid = $studyplan->id(); } + /** + * Remove a value from an array + * @param array $array The array to process + * @param mixed $value The value to remove + * @return array The array with the specified value removed + */ private static function array_remove_value($array, $value) { $a = []; foreach ($array as $v) { @@ -47,6 +65,12 @@ class cascadecohortsync { return $a; } + /** + * Get or create a group for the cohort to synch to this course + * @param int $courseid ID of the course + * @param string $groupname Name of the group + * @return int Id of the found or created group + */ private static function uploadenrolmentmethods_get_group($courseid, $groupname) { // Function shamelessly copied from tool/uploadenrolmentmethods/locallib.php. global $DB, $CFG; @@ -67,6 +91,9 @@ class cascadecohortsync { return $groupid; } + /** + * Enroll all cohorts associated to the studyplan in the courses linked to this studyplan + */ public function sync() { global $DB; @@ -214,6 +241,5 @@ class cascadecohortsync { } } } - } } diff --git a/classes/cascadeusersync.php b/classes/cascadeusersync.php index fcb6e9f..6674cea 100644 --- a/classes/cascadeusersync.php +++ b/classes/cascadeusersync.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Synchronize enrolled users in courses with users associated with studyplans these courses are in * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -27,14 +27,30 @@ require_once($CFG->libdir.'/externallib.php'); use \local_treestudyplan\studyplan; +/** + * Task class to synchronize enrolled users in courses with users associated with studyplans these courses are in + */ class cascadeusersync { + /** + * The method to use for enrolling students + * @var string + */ private const METHOD = "manual"; + /** @var studyplan */ private $studyplan; + /** + * Create a synchronization task for a studyplan + * @param studyplan $studyplan The studyplan to enrol students for + */ public function __construct(studyplan $studyplan) { $this->studyplan = $studyplan; } + + /** + * Enroll all users associated to the studyplan in the courses linked to this studyplan + */ public function sync() { global $DB; diff --git a/classes/contextinfo.php b/classes/contextinfo.php index 01b6b29..5ffb405 100644 --- a/classes/contextinfo.php +++ b/classes/contextinfo.php @@ -14,20 +14,35 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Class to abstract information about (category) context for web service export * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ namespace local_treestudyplan; +use \context; +/** + * Class to abstract information about (category) context for web service export + */ class contextinfo { + /** @var context */ public $context; - public function __construct($context) { + + /** + * Create new based on context + * @param context $context The context to describe + */ + public function __construct(context $context) { $this->context = $context; } + /** + * Describe the result for the webservice model + * @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([ "name" => new \external_value(PARAM_TEXT, 'context name'), @@ -37,6 +52,10 @@ class contextinfo { ], 'context information', $value); } + /** + * Make the webservice result model + * @return array Webservice value + */ public function model() { $ctxpath = array_reverse($this->context->get_parent_context_ids(true)); @@ -55,11 +74,21 @@ class contextinfo { ]; } + /** + * Make new Contextinfo for context id + * @param int $contextid Context id + * @return self Contextinfo based on context id + */ public static function by_id($contextid): self { return new self(self::context_by_id($contextid)); } - public static function context_by_id($contextid): \context { + /** + * Find context by id, but also return system context for context id 0 + * @param int $contextid Context id + * @return context The context + */ + private static function context_by_id($contextid): \context { if ($contextid <= 1) { $contextid = 1; } diff --git a/classes/local/gradegenerator.php b/classes/local/gradegenerator.php index 674ba26..ac8a537 100644 --- a/classes/local/gradegenerator.php +++ b/classes/local/gradegenerator.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Generate random grades and feedback to initialize development environment * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -23,10 +23,21 @@ namespace local_treestudyplan\local; use Exception; - +/** + * Generate random grades and feedback to initialize development environment + */ class gradegenerator { + + /** + * Table to store ficional skill data for students + * @var array + */ private $table = []; + /** + * Lorem ipsum text to use if fortune is not available + * @var string[] + */ private static $loremipsum = [ "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "Etiam scelerisque ligula porttitor velit sollicitudin blandit.", @@ -85,6 +96,10 @@ class gradegenerator { ]; + /** + * Generate random feedback from fortune or internal loremipsum text + * @return string Randomized text to use as feedback + */ private function generatedfeedback() { if (file_exists("/usr/games/fortune")) { // Get a fortune if it is available. @@ -95,10 +110,17 @@ class gradegenerator { } } + /** + * Constructor + */ public function __construct() { } + /** + * Register a new student in the skill table + * @param string $student Student identifier + */ public function addstudent(string $student) { if (!array_key_exists($student, $this->table)) { $this->table[$student] = [ @@ -109,6 +131,11 @@ class gradegenerator { } } + /** + * Add a specific skill for a student + * @param string $student Student identifier + * @param string $skill Skill identifier + */ public function addskill(string $student, string $skill) { $this->addstudent($student); if (!array_key_exists($skill, $this->table[$student]["skills"])) { @@ -121,13 +148,25 @@ class gradegenerator { } } - // Below is mostly just for reference in the json file. - public function add_username_info(string $student, $firstname, $lastname) { + /** + * Register a firstname and lastname for a student identifier for reference in the json file. + * @param string $student Student identifier + * @param string $firstname First name for student + * @param string $lastname Last name for student + */ + public function add_username_info(string $student, string $firstname, string $lastname) { $this->addstudent($student); $this->table[$student]["firstname"] = $firstname; $this->table[$student]["lastname"] = $lastname; } + /** + * Generate a number of random results for a given student and skill + * @param string $student Student identifier + * @param string $skill Skill identifier + * @param int $count Number of results to generate + * @return array Raw outcomes + */ public function generateraw($student, $skill, $count ) { $this->addskill($student, $skill); $int = $this->table[$student]["skills"][$skill]["intelligence"]; @@ -166,7 +205,18 @@ class gradegenerator { return $results; } - public function generate($student, $skill, array $gradeinfos ) { + /** + * Generate results for a number of gradeinfo + * Returns (object)[ "gi" => , + * "grade" => + * "fb" => + * ]; + * @param string $student Student identifier + * @param string $skill Skill identifier + * @param gradeinfo[] $gradeinfos + * @return stdClass[] List of gradeinfo related results ready to add + */ + public function generate(string $student, string $skill, array $gradeinfos ) { global $DB; $table = "local_treestudyplan_gradecfg"; @@ -267,24 +317,46 @@ class gradegenerator { return $rlist; } + /** + * Get a fictional student's performance stats + * @param string $student Student identifier + * @return array Used stats for student + */ public function getstats($student) { return $this->table[$student]; } + + /** + * Store skills table into a string + * @return string|null Json encoded string of the skills table + */ public function serialize(): ?string { return json_encode([ "table" => $this->table], JSON_PRETTY_PRINT); } + /** + * Load skills table from stored data + * @param string $data Json encoded string of the skills table + */ public function unserialize(string $data): void { $o = json_decode($data, true); $this->table = $o["table"]; } + /** + * Store skills table to file + * @param string $filename The file to use + */ public function to_file(string $filename) { $filename = self::expand_tilde($filename); file_put_contents($filename, $this->serialize()); } + /** + * Load skills table from file + * @param string $filename The file to use + */ public function from_file(string $filename) { $filename = self::expand_tilde($filename); if (file_exists($filename)) { @@ -298,6 +370,11 @@ class gradegenerator { } } + /** + * Internal function to properly handle the ~ symbol in unix context + * @param string $path A unix path + * @return string Unix path with ~ symbol properly expanded to user home dir + */ private static function expand_tilde($path) { if (function_exists('posix_getuid') && strpos($path, '~') !== false) { $info = posix_getpwuid(posix_getuid()); diff --git a/classes/reportinvite_form.php b/classes/reportinvite_form.php index 0b42f4d..715b772 100644 --- a/classes/reportinvite_form.php +++ b/classes/reportinvite_form.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Form to edit invitations to view the user's studyplans * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -25,9 +25,15 @@ defined('MOODLE_INTERNAL') || die(); require_once("$CFG->libdir/formslib.php"); require_once("$CFG->dirroot/local/treestudyplan/lib.php"); +/** +* Form to edit invitations to view the user's studyplans + */ class reportinvite_form extends moodleform { // Add elements to form. + /** + * Setup form + */ public function definition() { global $CFG; @@ -54,11 +60,21 @@ class reportinvite_form extends moodleform { $this->add_action_buttons(); } - // Custom validation should be added here. + + /** + * Custom validation should be added here. + * @param array $data Supplied user data + * @param array $files Any uploaded files + * @return array validation data + */ public function validation($data, $files) { return array(); } + /** + * Get supplied user data + * @return array The supplied data + */ public function get_data() { global $DB, $USER; diff --git a/classes/success.php b/classes/success.php index 0025234..d8c9ae4 100644 --- a/classes/success.php +++ b/classes/success.php @@ -67,7 +67,7 @@ class success { } /** - * Describe the result for the + * Describe the result for the webservice model * @return external_single_structure */ public static function structure() { @@ -80,7 +80,6 @@ class success { /** * Make the webservice result model - * * @return array Webservice value */ public function model() { diff --git a/classes/teachingfinder.php b/classes/teachingfinder.php index c06810e..2c9e0ba 100644 --- a/classes/teachingfinder.php +++ b/classes/teachingfinder.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 find and cache which studyplans a teacher is teaching courses in * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -22,9 +22,21 @@ namespace local_treestudyplan; +/** + * Class to find and cache which studyplans a teacher is teaching courses in + */ class teachingfinder { + /** + * Table name used for caching teacher info + * @var string + */ const TABLE = "local_treestudyplan_teachers"; + + /** + * List all studyplans the vurrent user is teaching + * @return studyplan[] List of studyplans + */ public static function list_my_plans() { global $USER, $DB; $userid = $USER->id; @@ -43,9 +55,10 @@ class teachingfinder { } /** - * Find The active studyplans where the specified user is a teacher + * Find The active studyplan pages where the specified user is a teacher * (Has the mod/assign::grade capability in one of the linked courses) - * TODO: OPTIMIZE THIS CHECK!!! + * @param int $userid The userid to check teacher rights for + * @return int[] List of page id's a teacher is teaching courses in */ public static function update_teaching_cache($userid) { global $DB; @@ -95,11 +108,20 @@ class teachingfinder { return $list; } + /** + * List of recognized teacher id's + * @return intp[] + */ public static function list_teacher_ids() { global $DB; return $DB->get_fieldset_sql("SELECT DISTINCT teacher_id FROM {".self::TABLE."}"); } + /** + * Get the last time of update for the specified teacher + * @param int $teacherid User id of teacher + * @return int Unix timestamp + */ public static function get_update_time($teacherid): int { global $DB; $r = $DB->get_field_sql("SELECT MIN(update_time) FROM {".self::TABLE."} WHERE teacher_id=:teacher_id",