PHPDoc documentation

classes/badgeinfo.php

@@ -48,6 +48,10 @@ class badgeinfo {
         $this->badge = $badge;
     }
 
+    /**
+     * Return full name
+     * @return string
+     */
     public function name() {
         return $this->badge->name;
     }

classes/courseinfo.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 process information about a course
  * @package    local_treestudyplan
  * @copyright  2023 P.M. Kuipers
  * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -33,36 +33,70 @@ use \grade_item;
 use \grade_scale;
 use \grade_outcome;
 
+/**
+ * Class to process information about a course
+ */
 class courseinfo {
-    /** @var string */
+    /**
+     * Table name used in this class
+     * @var string */
     const TABLE = 'course';
 
+    /** @var stdClass */
     private $course;
+    /** @var \context */
     private $context;
+    /** @var \context */
     private $coursecontext;
+    /** @var studyitem */
     private $studyitem;
+    /** @var array */
     private static $contentitems = null;
 
+    /**
+     * Return database identifier
+     * @return int
+     */
     public function id() {
         return $this->course->id;
     }
 
+    /**
+     * Return short name
+     * @return string
+     */
     public function shortname() {
         return $this->course->shortname;
     }
 
+    /**
+     * Return course record
+     * @return stdClass
+     */
     public function course() {
-        return $this->course; // Php arrays are assigned by copy.
+        return $this->course;
     }
 
+    /**
+     * Return course context
+     * @return \context
+     */
     public function course_context() {
         return $this->coursecontext;
     }
 
+    /**
+     * Return course's category context
+     * @return \context
+     */
     public function category_context() {
         return $this->context;
     }
 
+    /**
+     * Get content items (activity icons) from the repository
+     * @return content_item[]
+     */
     protected function get_contentitems() {
         global $PAGE;
         if (empty(static::$contentitems)) {
@@ -72,11 +106,19 @@ class courseinfo {
         return static::$contentitems;
     }
 
-    protected function am_teacher() {
+    /**
+     * Check if current user is teacher in this course
+     * @return book
+     */
+    protected function am_teacher() : bool {
         global $USER;
         return is_enrolled($this->coursecontext, $USER, 'mod/assign:grade');
     }
 
+    /**
+     * Check if specified user can select gradables in this course
+     * @param int $userid User id to check for . Leave empty to check current user
+     */
     protected function i_can_select_gradables($userid = -1) {
         global $USER, $DB;
         if ($userid <= 0) {
@@ -87,6 +129,11 @@ class courseinfo {
         return($usr && is_enrolled($this->coursecontext, $usr, 'local/treestudyplan:selectowngradables'));
     }
 
+    /**
+     * Get specific contentitem (activity icons) by name
+     * @param mixed $name Name of content item
+     * @return content_item|null
+     */
     public static function get_contentitem($name) {
         $contentitems = static::get_contentitems();
         for ($i = 0; $i < count($contentitems); $i++) {
@@ -97,6 +144,11 @@ class courseinfo {
         return null;
     }
 
+    /**
+     * Construct courseinfo based on course id and 
+     * @param int $id Course id
+     * @param studyitem|null $studyitem Studyitem linking this course (if applicable)
+     */
     public function __construct($id, studyitem $studyitem = null) {
         global $DB;
         $this->studyitem = $studyitem;
@@ -105,17 +157,32 @@ class courseinfo {
         $this->coursecontext = \context_course::instance($this->course->id);
     }
 
+    /**
+     * Check if a course with the given ID exists
+     * @param int $id Course id
+     * @return bool
+     */
     public static function exists($id) {
         global $DB;
         return is_numeric($id) && $DB->record_exists(self::TABLE, ['id' => $id]);
     }
 
+    /**
+     * Find course id from shortname
+     * @param string $shortname Shortname of the course
+     * @return int Course id
+     */
     public static function id_from_shortname($shortname) {
         global $DB;
 
         return $DB->get_field(self::TABLE, "id", ['shortname' => $shortname]);
     }
 
+    /** 
+     * Determine course timing [future, present or past] based on a course date
+     * @param stdClass $course Course database record
+     * @return string 'future', 'present' or 'past'
+     */
     public static function coursetiming($course) {
         $now = time();
         if ($now > $course->startdate) {
@@ -129,10 +196,18 @@ class courseinfo {
         }
     }
 
+    /** 
+     * Determine course timing for this course [future, present or past]
+     * @return string 'future', 'present' or 'past'
+     */
     public function timing() {
         return self::coursetiming($this->course);
     }
 
+    /**
+     * Determine proper display name for this course based on config settings, custom fields etc...
+     * @return string Display name for the course
+     */
     public function displayname() {
         $displayfield = get_config("local_treestudyplan", "display_field");
         if ($displayfield == "idnumber") {
@@ -158,6 +233,11 @@ class courseinfo {
         return $this->course->shortname;
     }
 
+    /**
+     * Webservice structure for basic info
+     * @param int $value Webservice requirement constant
+     * @return external_single_structure Webservice output structure
+     */
     public static function simple_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'linked course id'),
@@ -168,6 +248,10 @@ class courseinfo {
         ], 'referenced course information', $value);
     }
 
+     /**
+     * Webservice model for basic info
+     * @return array Webservice data model
+     */
     public function simple_model() {
         $contextinfo = new contextinfo($this->context);
         $info = [
@@ -209,6 +293,8 @@ class courseinfo {
 
     /**
      * Webservice model for editor info
+     * @param studyitem $studyitem Specify a specific study item to check gradable selections for. Leave empty to use default
+     * @param bool $usecorecompletioninfo Whether to use corecompletion info instead of custom selected gradables
      * @return array Webservice data model
      */
     public function editor_model(studyitem $studyitem = null, $usecorecompletioninfo = false) {
@@ -235,10 +321,10 @@ class courseinfo {
         ];
 
         if (!$usecorecompletioninfo) {
-            $gradables = gradeinfo::list_course_gradables($this->course, $studyitem);
+            $gradables = gradeinfo::list_course_gradables($this->course, $studyitem ? $studyitem : $this->studyitem );
 
             foreach ($gradables as $gradable) {
-                $info['grades'][] = $gradable->editor_model($studyitem);
+                $info['grades'][] = $gradable->editor_model($studyitem ? $studyitem : $this->studyitem);
             }
         } else {
             $cc = new corecompletioninfo($this->course);
@@ -272,6 +358,7 @@ class courseinfo {
     /**
      * Webservice model for user info
      * @param int $userid ID of user to check specific info for
+     * @param bool $usecorecompletioninfo Whether to use corecompletion info instead of custom selected gradables
      * @return array Webservice data model
      */
     public function user_model($userid, $usecorecompletioninfo = false) {

classes/gradeinfo.php

@@ -102,7 +102,7 @@ class gradeinfo {
      * Get the gradingscanner
      * @return gradingscanner
      */
-    public function get_gradingscanner() : gradingscanner{
+    public function get_gradingscanner() : gradingscanner {
         return $this->gradingscanner;
     }
 
@@ -110,7 +110,7 @@ class gradeinfo {
      * Get the grade's scale if applicable
      * @return grade_scale|null
      */
-    public function get_scale() : ?grade_scale{
+    public function get_scale() : ?grade_scale {
         return $this->scale;
     }
 
@@ -468,7 +468,7 @@ class gradeinfo {
      * @param studyitem $studyitem The studyitem to search for
      * @return self[] Array of gradeinfo
      */
-    public static function list_studyitem_gradables(studyitem $studyitem) : array{
+    public static function list_studyitem_gradables(studyitem $studyitem) : array {
         global $DB;
         $table = 'local_treestudyplan_gradeinc';
         $list = [];

classes/local/aggregators/core_aggregator.php

@@ -233,7 +233,7 @@ class core_aggregator extends \local_treestudyplan\aggregator {
      * @return int Aggregated completion as completion class constant
      */
     public function grade_completion(gradeinfo $gradeinfo, $userid) {
-        // CORE COMPLETION DOESN'T REALLY USE THIS FUNCTION
+        // CORE COMPLETION DOESN'T REALLY USE THIS FUNCTION.
 
         global $DB;
         $table = "local_treestudyplan_gradecfg";

classes/period.php

@@ -130,6 +130,10 @@ class period {
         $this->page = studyplanpage::find_by_id($this->r->page_id);
     }
 
+    /**
+     * Return database identifier
+     * @return int
+     */
     public function id() {
         return $this->id;
     }
@@ -142,10 +146,18 @@ class period {
         return $this->page;
     }
 
+    /**
+     * Return short name
+     * @return string
+     */
     public function shortname() {
         return $this->r->shortname;
     }
 
+    /**
+     * Return full name
+     * @return string
+     */
     public function fullname() {
         return $this->r->fullname;
     }

classes/reportinvite_form.php

@@ -26,7 +26,7 @@ require_once("$CFG->libdir/formslib.php");
 require_once("$CFG->dirroot/local/treestudyplan/lib.php");
 
 /**
-* Form to edit invitations to view the user's studyplans
+ * Form to edit invitations to view the user's studyplans
  */
 class reportinvite_form extends moodleform {
     // Add elements to form.

classes/studyitem.php

@@ -52,6 +52,11 @@ class studyitem {
     /** @var aggragator */
     private $aggregator;
 
+
+    /**
+     * Return the context the studyplan is associated to
+     * @return \context
+     */
     public function context(): \context {
         return $this->studyline->context();
     }
@@ -80,6 +85,10 @@ class studyitem {
         $this->aggregator = $this->studyline()->studyplan()->aggregator();
     }
 
+    /**
+     * Return database identifier
+     * @return int
+     */
     public function id() {
         return $this->id;
     }

classes/studyline.php

@@ -59,6 +59,11 @@ class studyline {
     /** @var studyplan*/
     private $studyplan;
 
+
+    /**
+     * Return the context the studyplan is associated to
+     * @return \context
+     */
     public function context(): \context {
         return $this->studyplan->context();
     }
@@ -86,10 +91,18 @@ class studyline {
         $this->studyplan = $this->page->studyplan();
     }
 
+    /**
+     * Return database identifier
+     * @return int
+     */
     public function id() {
         return $this->id;
     }
 
+    /**
+     * Return full name
+     * @return string
+     */
     public function name() {
         return $this->r->name;
     }

classes/studyplan.php

@@ -65,14 +65,26 @@ class studyplan {
         $this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config);
     }
 
+    /**
+     * Return database identifier
+     * @return int
+     */
     public function id() {
         return $this->id;
     }
 
+    /**
+     * Return short name
+     * @return string
+     */
     public function shortname() {
         return $this->r->shortname;
     }
 
+    /**
+     * Return full name
+     * @return string
+     */
     public function name() {
         return $this->r->name;
     }
@@ -88,7 +100,8 @@ class studyplan {
     }
 
     /**
-     * Return the context this studyplan is associated to
+     * Return the context the studyplan is associated to
+     * @return \context
      */
     public function context(): \context {
         if (!isset($this->context)) {
@@ -103,6 +116,11 @@ class studyplan {
         return $this->context;
     }
 
+    /**
+     * Webservice structure for basic info
+     * @param int $value Webservice requirement constant
+     * @return external_single_structure Webservice output structure
+     */
     public static function simple_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyplan'),
@@ -118,6 +136,10 @@ class studyplan {
         ], 'Basic studyplan info', $value);
     }
 
+     /**
+     * Webservice model for basic info
+     * @return array Webservice data model
+     */
     public function simple_model() {
         $pages = [];
         foreach ($this->pages() as $p) {

classes/studyplanpage.php

@@ -60,6 +60,10 @@ class studyplanpage {
         $this->studyplan = studyplan::find_by_id($this->r->studyplan_id);
     }
 
+    /**
+     * Return database identifier
+     * @return int
+     */
     public function id() {
         return $this->id;
     }
@@ -68,6 +72,10 @@ class studyplanpage {
         return $this->studyplan;
     }
 
+    /**
+     * Return short name
+     * @return string
+     */
     public function shortname() {
         return $this->r->shortname;
     }
@@ -76,6 +84,10 @@ class studyplanpage {
         return $this->r->periods;
     }
 
+    /**
+     * Return full name
+     * @return string
+     */
     public function fullname() {
         return $this->r->fullname;
     }
@@ -94,6 +106,11 @@ class studyplanpage {
 
     }
 
+    /**
+     * Webservice structure for basic info
+     * @param int $value Webservice requirement constant
+     * @return external_single_structure Webservice output structure
+     */
     public static function simple_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyplan page'),
@@ -107,6 +124,10 @@ class studyplanpage {
         ], 'Studyplan page basic info', $value);
     }
 
+     /**
+     * Webservice model for basic info
+     * @return array Webservice data model
+     */
     public function simple_model() {
         return [
             'id' => $this->r->id,

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 <https://www.gnu.org/licenses/>.
 /**
-* Developer CLI tool. Fill all the gradables in a study plan with random values
+ * 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

scss/readme-moodle.txt

@@ -16,5 +16,3 @@ production environments, the compiler will compile it into both css/devstyles.cs
 and styles.css
 
 The grunt command to compile is 'grunt scssplugin'
-
-