PHPDoc documentation

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 <https://www.gnu.org/licenses/>.
 /**
- *
+ * 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([

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 <https://www.gnu.org/licenses/>.
 /**
- *
+ * 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 {
                 }
             }
         }
-
     }
 }

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 <https://www.gnu.org/licenses/>.
 /**
- *
+ * 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;
 

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 <https://www.gnu.org/licenses/>.
 /**
- *
+ * 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;
         }

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 <https://www.gnu.org/licenses/>.
 /**
- *
+ * 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" => <gradeinfo object>,
+     *                   "grade" => <randomized grade>
+     *                   "fb" => <randomized feedback>
+     *                 ];
+     * @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());

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 <https://www.gnu.org/licenses/>.
 /**
- *
+ * 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;
 

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() {

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 <https://www.gnu.org/licenses/>.
 /**
- *
+ * 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",