PHPDoc documentation

classes/associationservice.php

@@ -100,6 +100,10 @@ class associationservice extends \external_api {
 
     }
 
+    /**
+     * Parameter description for webservice function list_cohort
+     * @return \external_function_parameters
+     */
     public static function list_cohort_parameters() {
         return new \external_function_parameters( [
             'like' => new \external_value(PARAM_TEXT, 'search text', VALUE_OPTIONAL),
@@ -108,6 +112,10 @@ class associationservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function list_cohort
+     * @return \external_description
+     */
     public static function list_cohort_returns() {
         return new \external_multiple_structure(self::cohort_structure());
     }
@@ -146,6 +154,10 @@ class associationservice extends \external_api {
         return $cohorts;
     }
 
+    /**
+     * Parameter description for webservice function find_user
+     * @return \external_function_parameters
+     */
     public static function find_user_parameters() {
         return new \external_function_parameters( [
             'like' => new \external_value(PARAM_TEXT, 'search text'),
@@ -154,6 +166,10 @@ class associationservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function find_user
+     * @return \external_description
+     */
     public static function find_user_returns() {
         return new \external_multiple_structure(self::user_structure());
     }
@@ -189,6 +205,10 @@ class associationservice extends \external_api {
         return $users;
     }
 
+    /**
+     * Parameter description for webservice function connect_cohort
+     * @return \external_function_parameters
+     */
     public static function connect_cohort_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
@@ -196,6 +216,10 @@ class associationservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function connect_cohort
+     * @return \external_description
+     */
     public static function connect_cohort_returns() {
         return new \external_single_structure([
             "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'),
@@ -225,6 +249,10 @@ class associationservice extends \external_api {
 
     }
 
+    /**
+     * Parameter description for webservice function disconnect_cohort
+     * @return \external_function_parameters
+     */
     public static function disconnect_cohort_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
@@ -232,6 +260,10 @@ class associationservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function disconnect_cohort
+     * @return \external_description
+     */
     public static function disconnect_cohort_returns() {
         return new \external_single_structure([
             "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'),
@@ -261,6 +293,10 @@ class associationservice extends \external_api {
 
     }
 
+    /**
+     * Parameter description for webservice function connect_user
+     * @return \external_function_parameters
+     */
     public static function connect_user_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
@@ -268,6 +304,10 @@ class associationservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function connect_user
+     * @return \external_description
+     */
     public static function connect_user_returns() {
         return new \external_single_structure([
             "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'),
@@ -296,6 +336,10 @@ class associationservice extends \external_api {
         }
     }
 
+    /**
+     * Parameter description for webservice function disconnect_user
+     * @return \external_function_parameters
+     */
     public static function disconnect_user_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
@@ -303,6 +347,10 @@ class associationservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function disconnect_user
+     * @return \external_description
+     */
     public static function disconnect_user_returns() {
         return new \external_single_structure([
             "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'),
@@ -330,12 +378,20 @@ class associationservice extends \external_api {
         }
     }
 
+    /**
+     * Parameter description for webservice function associated_users
+     * @return \external_function_parameters
+     */
     public static function associated_users_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
         ] );
     }
 
+    /**
+     * Return value description for webservice function associated_users
+     * @return \external_description
+     */
     public static function associated_users_returns() {
         return new \external_multiple_structure(self::user_structure());
     }
@@ -359,12 +415,20 @@ class associationservice extends \external_api {
         return $users;
     }
 
+    /**
+     * Parameter description for webservice function associated_cohorts
+     * @return \external_function_parameters
+     */
     public static function associated_cohorts_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
         ] );
     }
 
+    /**
+     * Return value description for webservice function associated_cohorts
+     * @return \external_description
+     */
     public static function associated_cohorts_returns() {
         return new \external_multiple_structure(self::cohort_structure());
     }
@@ -386,12 +450,20 @@ class associationservice extends \external_api {
         return $cohorts;
     }
 
+    /**
+     * Parameter description for webservice function all_associated
+     * @return \external_function_parameters
+     */
     public static function all_associated_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
         ] );
     }
 
+    /**
+     * Return value description for webservice function all_associated
+     * @return \external_description
+     */
     public static function all_associated_returns() {
         return new \external_multiple_structure(self::user_structure());
     }
@@ -443,12 +515,20 @@ class associationservice extends \external_api {
         });
     }
 
+    /**
+     * Parameter description for webservice function cascade_cohortsync
+     * @return \external_function_parameters
+     */
     public static function cascade_cohortsync_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL),
         ] );
     }
 
+    /**
+     * Return value description for webservice function cascade_cohortsync
+     * @return \external_description
+     */
     public static function cascade_cohortsync_returns() {
         return success::structure();
     }

classes/badgeinfo.php

@@ -63,6 +63,11 @@ class badgeinfo {
         return is_numeric($id) && $DB->record_exists('badge', array('id' => $id));
     }
 
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of badge'),
@@ -81,6 +86,10 @@ class badgeinfo {
         ], "Badge info", $value);
     }
 
+    /**
+     * Webservice model for editor info
+     * @return array Webservice data model
+     */
     public function editor_model(array $studentlist = null) {
         if ($this->badge->type == BADGE_TYPE_SITE) {
             $context = \context_system::instance();
@@ -114,6 +123,11 @@ class badgeinfo {
         return $model;
     }
 
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of badge'),
@@ -132,6 +146,11 @@ class badgeinfo {
         ], "Badge info", $value);
     }
 
+    /**
+     * Webservice model for user info
+     * @param int $userid ID of user to check specific info for
+     * @return array Webservice data model
+     */
     public function user_model($userid) {
         global $DB;
         if ($this->badge->type == BADGE_TYPE_SITE) {

classes/corecompletioninfo.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 collect course completion info for a given course
  * @package    local_treestudyplan
  * @copyright  2023 P.M. Kuipers
  * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -33,16 +33,36 @@ use \grade_item;
 use \grade_scale;
 use \grade_outcome;
 
+/**
+ * Class to collect course completion info for a given course
+ */
 class corecompletioninfo {
+    /** @var \stdClass */
     private $course;
+    /** @var \completion_info */
     private $completion;
+    /** @var \course_modinfo */
     private $modinfo;
+
+    /** 
+     * Cached dict of completion:: constants to equivalent webservice strings
+     * @var array */
     private static $completionhandles = null;
+    /**
+     * Cached dict of all completion type constants to equivalent strings
+     * @var array */
     private static $completiontypes = null;
 
+    /**
+     * Course id of relevant course
+     */
     public function id() {
         return $this->course->id;
     }
+    /**
+     * Construct new object for a given course
+     * @param \stdClass $course Course database record
+     */
     public function __construct($course) {
         global $DB;
         $this->course = $course;
@@ -50,6 +70,10 @@ class corecompletioninfo {
         $this->modinfo = get_fast_modinfo($this->course);
     }
 
+    /**
+     * Get dictionary of all completion types as CONST => 'string'
+     * @return array
+     */
     public static function completiontypes() {
         /*  While it is tempting to use the global array COMPLETION_CRITERIA_TYPES,
             so we don't have to manually add any completion types if moodle decides to add a few.
@@ -79,7 +103,7 @@ class corecompletioninfo {
 
     /**
      * Translate a numeric completion constant to a text string
-     * @param $completion The completion code as defined in completionlib.php to translate to a text handle
+     * @param int $completion The completion code as defined in completionlib.php to translate to a text handle
      */
     public static function completion_handle($completion) {
         if (empty(self::$completionhandles)) {
@@ -94,6 +118,11 @@ class corecompletioninfo {
         return self::$completionhandles[$completion] ?? "undefined";
     }
 
+    /**
+     * Webservice editor structure for completion_item
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function completion_item_editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'criteria id', VALUE_OPTIONAL),
@@ -109,6 +138,11 @@ class corecompletioninfo {
          ], 'completion type', $value);
     }
 
+    /**
+     * Webservice editor structure for completion_type
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function completion_type_editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "items" => new \external_multiple_structure(self::completion_item_editor_structure(), 'subitems', VALUE_OPTIONAL),
@@ -119,6 +153,16 @@ class corecompletioninfo {
          ], 'completion type', $value);
     }
 
+    /**
+     * Webservice editor structure for course completion
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
            "conditions" => new \external_multiple_structure(self::completion_type_editor_structure(), 'completion conditions'),
@@ -127,6 +171,11 @@ class corecompletioninfo {
         ], 'course completion info', $value);
     }
 
+    /**
+     * Webservice user view structure for completion_item
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function completion_item_user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of completion', VALUE_OPTIONAL),
@@ -148,6 +197,11 @@ class corecompletioninfo {
          ], 'completion type', $value);
     }
 
+    /**
+     * Webservice user view structure for completion_type
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function completion_type_user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "items" => new \external_multiple_structure(self::completion_item_user_structure(), 'subitems', VALUE_OPTIONAL),
@@ -163,6 +217,16 @@ class corecompletioninfo {
          ], 'completion type', $value);
     }
 
+    /**
+     * Webservice user view structure for course completion
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "progress" => new \external_value(PARAM_INT, 'completed sub-conditions'),
@@ -176,10 +240,19 @@ class corecompletioninfo {
         ], 'course completion info', $value);
     }
 
+    /**
+     * Convert agregation method constant to equivalent string for webservice
+     * @param int $method COMPLETION_AGGREGATION_ALL || COMPLETION_AGGREGATION_ANY
+     * @return string 'all' or 'any'
+     */
     private static function aggregation_handle($method) {
         return ($method == COMPLETION_AGGREGATION_ALL) ? "all" : "any";
     }
 
+    /**
+     * Webservice model for editor info
+     * @return array Webservice data model
+     */
     public function editor_model() {
         global $DB, $CFG;
 
@@ -338,6 +411,12 @@ class corecompletioninfo {
         return $info;
     }
 
+    /**
+     * Determine overall completion for a given type
+     * @param int $typeaggregation COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY
+     * @param \completion_criteria_completion[] $completions List of completions to aggregate
+     * @return bool Completed or not
+     */
     private function aggregate_completions($typeaggregation, $completions) {
         $completed = 0;
         $count = count($completions);
@@ -354,6 +433,11 @@ class corecompletioninfo {
 
     }
 
+    /**
+     * Webservice model for user course completion info
+     * @param int $userid ID of user to check specific info for
+     * @return array Webservice data model
+     */
     public function user_model($userid) {
         global $DB;
 
@@ -464,6 +548,8 @@ class corecompletioninfo {
 
     /**
      * Get the grade for a certain course module
+     * @param \cm_info $cm Course module
+     * @param int $userid ID of user to retrieve grade for
      * @return stdClass|null object containing 'grade' and optional 'feedback' attribute
      */
     private function get_grade($cm, $userid) {
@@ -507,7 +593,8 @@ class corecompletioninfo {
     }
 
     /**
-     * Get the grade for a certain course module
+     * Get the overall grade for this course
+     * @param int $userid ID of user to retrieve grade for
      * @return stdClass|null object containing 'grade' and optional 'feedback' attribute
      */
     private function get_course_grade($userid) {

classes/courseinfo.php

@@ -181,6 +181,11 @@ class courseinfo {
         return $info;
     }
 
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'linked course id'),
@@ -202,6 +207,10 @@ class courseinfo {
         ], 'referenced course information', $value);
     }
 
+    /**
+     * Webservice model for editor info
+     * @return array Webservice data model
+     */
     public function editor_model(studyitem $studyitem = null, $usecorecompletioninfo = false) {
         global $DB;
         $contextinfo = new contextinfo($this->context);
@@ -239,6 +248,11 @@ class courseinfo {
         return $info;
     }
 
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'linked course id'),
@@ -255,6 +269,11 @@ class courseinfo {
         ], 'course information', $value);
     }
 
+    /**
+     * Webservice model for user info
+     * @param int $userid ID of user to check specific info for
+     * @return array Webservice data model
+     */
     public function user_model($userid, $usecorecompletioninfo = false) {
         global $DB;
         $contextinfo = new contextinfo($this->context);

classes/gradeinfo.php

@@ -253,6 +253,11 @@ class gradeinfo {
      * @param int $value Webservice requirement constant
      * @return external_single_structure Webservice output structure
      */
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'grade_item id'),
@@ -302,6 +307,11 @@ class gradeinfo {
      * @param int $value Webservice requirement constant
      * @return external_single_structure Webservice output structure
      */
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'grade_item id'),

classes/studentstudyplanservice.php

@@ -37,12 +37,20 @@ class studentstudyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function list_user_studyplans
+     * @return \external_function_parameters
+     */
     public static function list_user_studyplans_parameters() {
         return new \external_function_parameters([
             "userid" => new \external_value(PARAM_INT, 'id of student', VALUE_DEFAULT),
         ]);
     }
 
+    /**
+     * Return value description for webservice function list_user_studyplans
+     * @return \external_description
+     */
     public static function list_user_studyplans_returns() {
         return new \external_multiple_structure(
             studyplan::simple_structure()
@@ -69,12 +77,20 @@ class studentstudyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function get_user_studyplans
+     * @return \external_function_parameters
+     */
     public static function get_user_studyplans_parameters() {
         return new \external_function_parameters( [
             "userid" => new \external_value(PARAM_INT, 'id of user'),
         ] );
     }
 
+    /**
+     * Return value description for webservice function get_user_studyplans
+     * @return \external_description
+     */
     public static function get_user_studyplans_returns() {
         return new \external_multiple_structure(
             studyplan::user_structure()
@@ -102,6 +118,10 @@ class studentstudyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function get_user_studyplan
+     * @return \external_function_parameters
+     */
     public static function get_user_studyplan_parameters() {
         return new \external_function_parameters( [
             "userid" => new \external_value(PARAM_INT, 'id of user'),
@@ -109,6 +129,10 @@ class studentstudyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function get_user_studyplan
+     * @return \external_description
+     */
     public static function get_user_studyplan_returns() {
         return studyplan::user_structure();
     }
@@ -131,12 +155,20 @@ class studentstudyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function get_invited_studyplan
+     * @return \external_function_parameters
+     */
     public static function get_invited_studyplan_parameters() {
         return new \external_function_parameters( [
             "invitekey" => new \external_value(PARAM_RAW, 'invite key'),
         ] );
     }
 
+    /**
+     * Return value description for webservice function get_invited_studyplan
+     * @return \external_description
+     */
     public static function get_invited_studyplan_returns() {
         return new \external_multiple_structure(
             studyplan::user_structure()
@@ -174,10 +206,18 @@ class studentstudyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function list_own_studyplans
+     * @return \external_function_parameters
+     */
     public static function list_own_studyplans_parameters() {
         return new \external_function_parameters([]);
     }
 
+    /**
+     * Return value description for webservice function list_own_studyplans
+     * @return \external_description
+     */
     public static function list_own_studyplans_returns() {
         return new \external_multiple_structure(
             studyplan::simple_structure()
@@ -202,12 +242,20 @@ class studentstudyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function get_own_studyplan
+     * @return \external_function_parameters
+     */
     public static function get_own_studyplan_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of specific studyplan to provide', VALUE_DEFAULT),
         ] );
     }
 
+    /**
+     * Return value description for webservice function get_own_studyplan
+     * @return \external_description
+     */
     public static function get_own_studyplan_returns() {
         return new \external_multiple_structure(
             studyplan::user_structure()
@@ -246,12 +294,20 @@ class studentstudyplanservice extends \external_api {
      *                         *
      ***************************/
 
+    /**
+     * Parameter description for webservice function get_teaching_studyplans
+     * @return \external_function_parameters
+     */
     public static function get_teaching_studyplans_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of specific studyplan to provide', VALUE_DEFAULT),
         ] );
     }
 
+    /**
+     * Return value description for webservice function get_teaching_studyplans
+     * @return \external_description
+     */
     public static function get_teaching_studyplans_returns() {
         return new \external_multiple_structure(
             studyplan::editor_structure()

classes/studyitem.php

@@ -105,6 +105,11 @@ class studyitem {
         return is_numeric($id) && $DB->record_exists(self::TABLE, array('id' => $id));
     }
 
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of study item'),
@@ -124,6 +129,10 @@ class studyitem {
 
     }
 
+    /**
+     * Webservice model for editor info
+     * @return array Webservice data model
+     */
     public function editor_model() {
         return $this->generate_model("editor");
     }
@@ -343,6 +352,11 @@ class studyitem {
         ];
     }
 
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id"            => new \external_value(PARAM_INT, 'id of study item'),
@@ -362,6 +376,11 @@ class studyitem {
 
     }
 
+    /**
+     * Webservice model for user info
+     * @param int $userid ID of user to check specific info for
+     * @return array Webservice data model
+     */
     public function user_model($userid) {
         global $CFG, $DB;
 
@@ -503,6 +522,10 @@ class studyitem {
         return $new;
     }
 
+    /**
+     * Export essential information for export
+     * @return array information model
+     */
     public function export_model() {
         return $this->generate_model("export");
     }

classes/studyline.php

@@ -97,6 +97,11 @@ class studyline {
         return $this->r->shortname;
     }
 
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyline'),
@@ -115,6 +120,10 @@ class studyline {
         ]);
     }
 
+    /**
+     * Webservice model for editor info
+     * @return array Webservice data model
+     */
     public function editor_model() {
         return $this->generate_model("editor");
     }
@@ -261,6 +270,11 @@ class studyline {
         return $list;
     }
 
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyline'),
@@ -279,6 +293,11 @@ class studyline {
         ], 'Studyline with user info', $value);
     }
 
+    /**
+     * Webservice model for user info
+     * @param int $userid ID of user to check specific info for
+     * @return array Webservice data model
+     */
     public function user_model($userid) {
         // TODO: Integrate this function into generate_model() for ease of maintenance.
 
@@ -357,6 +376,10 @@ class studyline {
         return $new;
     }
 
+    /**
+     * Export essential information for export
+     * @return array information model
+     */
     public function export_model() {
         return $this->generate_model("export");
     }

classes/studyplan.php

@@ -138,6 +138,11 @@ class studyplan {
         ];
     }
 
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyplan'),
@@ -161,6 +166,10 @@ class studyplan {
             ], 'Studyplan full structure', $value);
     }
 
+    /**
+     * Webservice model for editor info
+     * @return array Webservice data model
+     */
     public function editor_model() {
         global $DB;
 
@@ -451,6 +460,11 @@ class studyplan {
         }
     }
 
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyplan'),
@@ -464,6 +478,11 @@ class studyplan {
 
     }
 
+    /**
+     * Webservice model for user info
+     * @param int $userid ID of user to check specific info for
+     * @return array Webservice data model
+     */
     public function user_model($userid) {
 
         $model = [
@@ -522,6 +541,10 @@ class studyplan {
         return [ "format" => "application/json", "content" => $json];
     }
 
+    /**
+     * Export essential information for export
+     * @return array information model
+     */
     public function export_model() {
         $model = [
             'name' => $this->r->name,
@@ -535,6 +558,10 @@ class studyplan {
         return $model;
     }
 
+    /**
+     * Export all pages 
+     * @return array information model
+     */
     public function export_pages_model() {
         $pages = [];
         foreach ($this->pages() as $p) {

classes/studyplanpage.php

@@ -120,6 +120,11 @@ class studyplanpage {
         ];
     }
 
+    /**
+     * Webservice structure for editor info
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function editor_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyplan'),
@@ -134,6 +139,10 @@ class studyplanpage {
             ], 'Studyplan page full structure', $value);
     }
 
+    /**
+     * Webservice model for editor info
+     * @return array Webservice data model
+     */
     public function editor_model() {
         global $DB;
 
@@ -218,6 +227,11 @@ class studyplanpage {
         }
     }
 
+    /**
+     * Webservice structure for userinfo
+     * @param int $value Webservice requirement constant
+     * @return \external_single_structure Webservice output structure
+     */
     public static function user_structure($value = VALUE_REQUIRED) {
         return new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of studyplan page'),
@@ -232,6 +246,11 @@ class studyplanpage {
         ], 'Studyplan page with user info', $value);
     }
 
+    /**
+     * Webservice model for user info
+     * @param int $userid ID of user to check specific info for
+     * @return array Webservice data model
+     */
     public function user_model($userid) {
 
         $model = [
@@ -416,6 +435,10 @@ class studyplanpage {
         return [ "format" => "application/json", "content" => $json];
     }
 
+    /**
+     * Export essential information for export
+     * @return array information model
+     */
     public function export_model() {
         $model = [
             'fullname' => $this->r->fullname,

classes/studyplanservice.php

@@ -41,12 +41,20 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function list_studyplans
+     * @return \external_function_parameters
+     */
     public static function list_studyplans_parameters() {
         return new \external_function_parameters([
             "context_id" => new \external_value(PARAM_INT, 'context to search in for studyplans', VALUE_DEFAULT),
         ]);
     }
 
+    /**
+     * Return value description for webservice function list_studyplans
+     * @return \external_description
+     */
     public static function list_studyplans_returns() {
         return new \external_multiple_structure( studyplan::simple_structure() );
     }
@@ -74,12 +82,20 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function get_studyplan_map
+     * @return \external_function_parameters
+     */
     public static function get_studyplan_map_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of a studyplan to check usage on', VALUE_REQUIRED),
         ] );
     }
 
+    /**
+     * Return value description for webservice function get_studyplan_map
+     * @return \external_description
+     */
     public static function get_studyplan_map_returns() {
         return  studyplan::editor_structure();
     }
@@ -100,12 +116,20 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function get_studyline_map
+     * @return \external_function_parameters
+     */
     public static function get_studyline_map_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of a studyline to check usage on', VALUE_DEFAULT),
         ]);
     }
 
+    /**
+     * Return value description for webservice function get_studyline_map
+     * @return \external_description
+     */
     public static function get_studyline_map_returns() {
         return new \external_multiple_structure( studyline::editor_structure() );
     }
@@ -123,6 +147,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function add_studyplan
+     * @return \external_function_parameters
+     */
     public static function add_studyplan_parameters() {
         return new \external_function_parameters( [
             "name" => new \external_value(PARAM_TEXT, 'name of studyplan'),
@@ -138,6 +166,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function add_studyplan
+     * @return \external_description
+     */
     public static function add_studyplan_returns() {
         return studyplan::simple_structure();
     }
@@ -169,6 +201,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function edit_studyplan
+     * @return \external_function_parameters
+     */
     public static function edit_studyplan_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of studyplan'),
@@ -185,6 +221,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function edit_studyplan
+     * @return \external_description
+     */
     public static function edit_studyplan_returns() {
         return studyplan::simple_structure();
     }
@@ -220,6 +260,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function delete_studyplan
+     * @return \external_function_parameters
+     */
     public static function delete_studyplan_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of studyplan'),
@@ -227,6 +271,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function delete_studyplan
+     * @return \external_description
+     */
     public static function delete_studyplan_returns() {
         return success::structure();
     }
@@ -244,6 +292,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function add_studyline
+     * @return \external_function_parameters
+     */
     public static function add_studyline_parameters() {
         return new \external_function_parameters( [
             "page_id" => new \external_value(PARAM_INT, 'id of studyplan to add line to'),
@@ -254,6 +306,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function add_studyline
+     * @return \external_description
+     */
     public static function add_studyline_returns() {
         return studyline::editor_structure();
     }
@@ -279,6 +335,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function edit_studyline
+     * @return \external_function_parameters
+     */
     public static function edit_studyline_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of studyline'),
@@ -288,6 +348,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function edit_studyline
+     * @return \external_description
+     */
     public static function edit_studyline_returns() {
         return studyline::editor_structure();
     }
@@ -311,12 +375,20 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function delete_studyline
+     * @return \external_function_parameters
+     */
     public static function delete_studyline_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of studyline'),
         ] );
     }
 
+    /**
+     * Return value description for webservice function delete_studyline
+     * @return \external_description
+     */
     public static function delete_studyline_returns() {
         return success::structure();
     }
@@ -335,6 +407,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function reorder_studylines
+     * @return \external_function_parameters
+     */
     public static function reorder_studylines_parameters() {
         return new \external_function_parameters( [
             "sequence" => new \external_multiple_structure(
@@ -346,6 +422,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function reorder_studylines
+     * @return \external_description
+     */
     public static function reorder_studylines_returns() {
         return success::structure();
     }
@@ -370,12 +450,20 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function get_studyitem
+     * @return \external_function_parameters
+     */
     public static function get_studyitem_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of a study item to retrieve'),
         ] );
     }
 
+    /**
+     * Return value description for webservice function get_studyitem
+     * @return \external_description
+     */
     public static function get_studyitem_returns() {
         return studyitem::editor_structure();
     }
@@ -393,6 +481,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function add_studyitem
+     * @return \external_function_parameters
+     */
     public static function add_studyitem_parameters() {
         return new \external_function_parameters( [
             "line_id" => new \external_value(PARAM_INT, 'id of related study line'),
@@ -409,6 +501,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function add_studyitem
+     * @return \external_description
+     */
     public static function add_studyitem_returns() {
         return studyitem::editor_structure();
     }
@@ -435,6 +531,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function edit_studyitem
+     * @return \external_function_parameters
+     */
     public static function edit_studyitem_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of study item'),
@@ -443,6 +543,10 @@ class studyplanservice extends \external_api {
         ]);
     }
 
+    /**
+     * Return value description for webservice function edit_studyitem
+     * @return \external_description
+     */
     public static function edit_studyitem_returns() {
         return studyitem::editor_structure();
     }
@@ -470,6 +574,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function reorder_studyitems
+     * @return \external_function_parameters
+     */
     public static function reorder_studyitems_parameters() {
         return new \external_function_parameters( [
             "items" => new \external_multiple_structure(
@@ -483,6 +591,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function reorder_studyitems
+     * @return \external_description
+     */
     public static function reorder_studyitems_returns() {
         return success::structure();
     }
@@ -502,12 +614,20 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function delete_studyitem
+     * @return \external_function_parameters
+     */
     public static function delete_studyitem_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of studyitem'),
         ] );
     }
 
+    /**
+     * Return value description for webservice function delete_studyitem
+     * @return \external_description
+     */
     public static function delete_studyitem_returns() {
         return success::structure();
     }
@@ -525,6 +645,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function connect_studyitems
+     * @return \external_function_parameters
+     */
     public static function connect_studyitems_parameters() {
         return new \external_function_parameters( [
             "from_id" => new \external_value(PARAM_INT, 'id of studyitem connect start '),
@@ -532,6 +656,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function connect_studyitems
+     * @return \external_description
+     */
     public static function connect_studyitems_returns() {
         return studyitemconnection::structure();
     }
@@ -551,6 +679,10 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function disconnect_studyitems
+     * @return \external_function_parameters
+     */
     public static function disconnect_studyitems_parameters() {
         return new \external_function_parameters( [
             "from_id" => new \external_value(PARAM_INT, 'id of studyitem '),
@@ -558,6 +690,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function disconnect_studyitems
+     * @return \external_description
+     */
     public static function disconnect_studyitems_returns() {
         return success::structure();
     }
@@ -575,10 +711,18 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function list_badges
+     * @return \external_function_parameters
+     */
     public static function list_badges_parameters() {
         return new \external_function_parameters( [] );
     }
 
+    /**
+     * Return value description for webservice function list_badges
+     * @return \external_description
+     */
     public static function list_badges_returns() {
         return new \external_multiple_structure(badgeinfo::editor_structure());
     }
@@ -605,6 +749,10 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function include_grade
+     * @return \external_function_parameters
+     */
     public static function include_grade_parameters() {
         return new \external_function_parameters( [
             "grade_id" => new \external_value(PARAM_INT, 'id of gradeitem '),
@@ -614,6 +762,10 @@ class studyplanservice extends \external_api {
             ] );
     }
 
+    /**
+     * Return value description for webservice function include_grade
+     * @return \external_description
+     */
     public static function include_grade_returns() {
         return success::structure();
     }
@@ -642,10 +794,18 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function list_aggregators
+     * @return \external_function_parameters
+     */
     public static function list_aggregators_parameters() {
         return new \external_function_parameters([]);
     }
 
+    /**
+     * Return value description for webservice function list_aggregators
+     * @return \external_description
+     */
     public static function list_aggregators_returns() {
         return aggregator::list_structure();
     }
@@ -661,6 +821,10 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function force_studyplan_scale
+     * @return \external_function_parameters
+     */
     public static function force_studyplan_scale_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan'),
@@ -668,6 +832,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function force_studyplan_scale
+     * @return \external_description
+     */
     public static function force_studyplan_scale_returns() {
         return new \external_multiple_structure(new \external_single_structure([
             "course" => courseinfo::simple_structure(),
@@ -780,10 +948,18 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function list_scales
+     * @return \external_function_parameters
+     */
     public static function list_scales_parameters() {
         return new \external_function_parameters( [] );
     }
 
+    /**
+     * Return value description for webservice function list_scales
+     * @return \external_description
+     */
     public static function list_scales_returns() {
         return new \external_multiple_structure(new \external_single_structure([
             "id" => new \external_value(PARAM_INT, 'id of scale'),
@@ -813,12 +989,20 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function disable_autoenddate
+     * @return \external_function_parameters
+     */
     public static function disable_autoenddate_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan'),
         ] );
     }
 
+    /**
+     * Return value description for webservice function disable_autoenddate
+     * @return \external_description
+     */
     public static function disable_autoenddate_returns() {
         return success::structure();
     }
@@ -856,6 +1040,10 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function duplicate_plan
+     * @return \external_function_parameters
+     */
     public static function duplicate_plan_parameters() {
         return new \external_function_parameters( [
             "plan_id" => new \external_value(PARAM_INT, 'id of plan to copy '),
@@ -864,6 +1052,10 @@ class studyplanservice extends \external_api {
             ] );
     }
 
+    /**
+     * Return value description for webservice function duplicate_plan
+     * @return \external_description
+     */
     public static function duplicate_plan_returns() {
         return studyplan::simple_structure();
     }
@@ -881,6 +1073,10 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function export_plan
+     * @return \external_function_parameters
+     */
     public static function export_plan_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '),
@@ -888,6 +1084,10 @@ class studyplanservice extends \external_api {
             ] );
     }
 
+    /**
+     * Return value description for webservice function export_plan
+     * @return \external_description
+     */
     public static function export_plan_returns() {
         return studyplan::export_structure();
     }
@@ -909,12 +1109,20 @@ class studyplanservice extends \external_api {
         }
     }
 
+    /**
+     * Parameter description for webservice function export_studylines
+     * @return \external_function_parameters
+     */
     public static function export_studylines_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '),
             ] );
     }
 
+    /**
+     * Return value description for webservice function export_studylines
+     * @return \external_description
+     */
     public static function export_studylines_returns() {
         return studyplan::export_structure();
     }
@@ -937,6 +1145,10 @@ class studyplanservice extends \external_api {
      *                          *
      ****************************/
 
+    /**
+     * Parameter description for webservice function import_plan
+     * @return \external_function_parameters
+     */
     public static function import_plan_parameters() {
         return new \external_function_parameters( [
             "content" => new \external_value(PARAM_TEXT, 'import file content'),
@@ -945,6 +1157,10 @@ class studyplanservice extends \external_api {
             ] );
     }
 
+    /**
+     * Return value description for webservice function import_plan
+     * @return \external_description
+     */
     public static function import_plan_returns() {
         return success::structure();
     }
@@ -963,6 +1179,10 @@ class studyplanservice extends \external_api {
         }
     }
 
+    /**
+     * Parameter description for webservice function import_studylines
+     * @return \external_function_parameters
+     */
     public static function import_studylines_parameters() {
         return new \external_function_parameters( [
             "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '),
@@ -971,6 +1191,10 @@ class studyplanservice extends \external_api {
             ] );
     }
 
+    /**
+     * Return value description for webservice function import_studylines
+     * @return \external_description
+     */
     public static function import_studylines_returns() {
         return success::structure();
     }
@@ -998,6 +1222,10 @@ class studyplanservice extends \external_api {
      *                                                      *
      ********************************************************/
 
+    /**
+     * Parameter description for webservice function submit_cm_editform
+     * @return \external_function_parameters
+     */
     public static function submit_cm_editform_parameters() {
         return new \external_function_parameters( [
             "cmid" => new \external_value(PARAM_INT, 'id of course module'),
@@ -1005,6 +1233,10 @@ class studyplanservice extends \external_api {
         ] );
     }
 
+    /**
+     * Return value description for webservice function submit_cm_editform
+     * @return \external_description
+     */
     public static function submit_cm_editform_returns() {
         return success::structure();
     }
@@ -1075,6 +1307,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function edit_period
+     * @return \external_function_parameters
+     */
     public static function edit_period_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of study item'),
@@ -1085,6 +1321,10 @@ class studyplanservice extends \external_api {
         ]);
     }
 
+    /**
+     * Return value description for webservice function edit_period
+     * @return \external_description
+     */
     public static function edit_period_returns() {
         return period::structure();
     }
@@ -1110,6 +1350,10 @@ class studyplanservice extends \external_api {
      *                      *
      ************************/
 
+    /**
+     * Parameter description for webservice function course_period_timing
+     * @return \external_function_parameters
+     */
     public static function course_period_timing_parameters() {
         return new \external_function_parameters( [
             "period_id" => new \external_value(PARAM_INT, 'Period number within page'),
@@ -1118,6 +1362,10 @@ class studyplanservice extends \external_api {
         ]);
     }
 
+    /**
+     * Return value description for webservice function course_period_timing
+     * @return \external_description
+     */
     public static function course_period_timing_returns() {
         return courseinfo::editor_structure();
     }
@@ -1175,6 +1423,10 @@ class studyplanservice extends \external_api {
         }
     }
 
+    /**
+     * Parameter description for webservice function set_studyitem_span
+     * @return \external_function_parameters
+     */
     public static function set_studyitem_span_parameters() {
         return new \external_function_parameters( [
             "id" => new \external_value(PARAM_INT, 'id of study item'),
@@ -1182,6 +1434,10 @@ class studyplanservice extends \external_api {
         ]);
     }
 
+    /**
+     * Return value description for webservice function set_studyitem_span
+     * @return \external_description
+     */
     public static function set_studyitem_span_returns() {
         return studyitem::editor_structure();
     }