enhanced PHP doc comments

dta/locallib.php

@@ -30,11 +30,11 @@ require_once($CFG->dirroot . '/mod/assign/submission/dta/utils/view.php');
  */
 class assign_submission_dta extends assign_submission_plugin {
 
-    /** 
+    /**
      * Broadly used in logic, parametrized for easier change.
      */
     const COMPONENT_NAME = "assignsubmission_dta";
-    /** 
+    /**
      * Draft file area for dta tests to be uploaded by the teacher.
      */
     const ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST = "tests_draft_dta";
@@ -168,11 +168,11 @@ class assign_submission_dta extends assign_submission_plugin {
     /**
      * Add elements to submission form
      *
-     * @param mixed $submission stdClass|null
-     * @param MoodleQuickForm $mform
-     * @param stdClass $data
-     * @param int $userid
-     * @return bool
+     * @param mixed $submissionorgrade stdClass|null submission or grade to show in the form
+     * @param MoodleQuickForm $mform form for adding elements
+     * @param stdClass $data data for filling the elements
+     * @param int $userid current user
+     * @return bool form elements added
      */
     public function get_form_elements_for_user($submissionorgrade, MoodleQuickForm $mform, stdClass $data, $userid): bool {
         // Prepare submission filearea.
@@ -213,6 +213,7 @@ class assign_submission_dta extends assign_submission_plugin {
     }
 
     /**
+     * Determines if a submission file area contains any files.
      * @param stdClass $submission submission to check
      * @return bool true if file count is zero
      */
@@ -221,7 +222,7 @@ class assign_submission_dta extends assign_submission_plugin {
     }
 
     /**
-     * Count the number of files in a filearea
+     * Counts the number of files in a filearea
      *
      * @param int $submissionid submission id to check
      * @param string $areaid filearea id to count

dta/models/DtaResult.php

@@ -25,28 +25,28 @@ defined('MOODLE_INTERNAL') || die();
  */
 class DtaResult {
 
-    /** 
+    /**
      * Broadly used in logic, parametrized for easier change.
      */
     const COMPONENT_NAME = "assignsubmission_dta";
 
-    /** 
-     * Package name of the test.
+    /**
+     * @var $packagename Package name of the test.
      */
     public $packagename;
-    
-    /** 
-     * Unit name of the test.
+
+    /**
+     * @var $classname Unit name of the test.
      */
     public $classname;
-    
-    /** 
-     * Name of the test.
+
+    /**
+     * @var $name Name of the test.
      */
     public $name;
 
     /**
-     * State is defined like below
+     * @var $state State is defined like below
      *
      *  0 UNKNOWN
      *  1 SUCCESS
@@ -55,32 +55,32 @@ class DtaResult {
      */
     public $state;
 
-    /** 
-     * Type of test failure if applicable, "" otherwise.
+    /**
+     * @var $failuretype Type of test failure if applicable, "" otherwise.
      */
     public $failuretype;
-    
-    /** 
-     * Reason of test failure if applicable, "" otherwise.
+
+    /**
+     * @var $failurereason Reason of test failure if applicable, "" otherwise.
      */    
     public $failurereason;
-    
-    /** 
-     * Stack trace of test failure if applicable, "" otherwise.
-     */    
+
+    /**
+     * @var $stacktrace Stack trace of test failure if applicable, "" otherwise.
+     */
     public $stacktrace;
 
-    /** 
-     * Column number of compile failure if applicable, "" otherwise.
-     */    
+    /**
+     * @var $columnnumber Column number of compile failure if applicable, "" otherwise.
+     */
     public $columnnumber;
-    /** 
-     * Line number of compile failure if applicable, "" otherwise.
-     */    
+    /**
+     * @var $linenumber Line number of compile failure if applicable, "" otherwise.
+     */
     public $linenumber;
-    /** 
-     * Position of compile failure if applicable, "" otherwise.
-     */    
+    /**
+     * @var $position Position of compile failure if applicable, "" otherwise.
+     */
     public $position;
 
     /**
@@ -109,32 +109,32 @@ class DtaResult {
  */
 class DtaResultSummary {
 
-    /** 
-     * Result timestamp for chronological ordering and deletion of previous results.
+    /**
+     * @var $timestamp Result timestamp for chronological ordering and deletion of previous results.
      */    
     public $timestamp;
-    
-    /** 
-     * Global stack trace if applicable, "" otherwise.
-     */    
+
+    /**
+     * @var $globalstacktrace Global stack trace if applicable, "" otherwise.
+     */
     public $globalstacktrace;
-    
-    /** 
-     * Successfully tested competencies according to tests and weights, "" otherwise.
-     */    
+
+    /**
+     * @var $successfultestcompetencies Successfully tested competencies according to tests and weights, "" otherwise.
+     */
     public $successfultestcompetencies;
-    /** 
-     * Overall tested competencies according to tests and weights, "" otherwise.
-     */    
+    /**
+     * @var overalltestcompetencies Overall tested competencies according to tests and weights, "" otherwise.
+     */
     public $overalltestcompetencies;
-    /** 
-     * List of detail results.
-     */    
+    /**
+     * @var results List of detail results.
+     */
     public $results;
 
     /**
      * Decodes the JSON result summary returned by the backend service call into the plugin PHP data structure.
-     * @param string $jsonString jsonString containing DtaResultSummary
+     * @param string $jsonstring jsonString containing DtaResultSummary
      * @return DtaResultSummary
      */
     public static function decodejson($jsonstring): DtaResultSummary {
@@ -154,7 +154,7 @@ class DtaResultSummary {
 
     /**
      * Decodes the array of JSON detail results returned by the backend service call into the plugin PHP data structure.
-     * @param array $jsonArray decoded json array of results array
+     * @param array $jsonarray decoded json array of results array
      * @return array of DtaResult
      */
     private static function decodejsonresultarray($jsonarray): array {

dta/utils/backend.php

@@ -14,9 +14,25 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * This file contains the backend webservice contact functionality for the DTA plugin
+ *
+ * @package    assignsubmission_dta
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
+ */
+ 
+/**
+ * backend webservice contact utility class
+ *
+ * @package assignsubmission_dta
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
+ */ 
 class DtaBackendUtils {
 
     /**
+     * Returns the base url of the backend webservice as configured in the administration settings.
      * @return string backend host base url
      */
     private static function getbackendbaseurl(): string {
@@ -30,11 +46,10 @@ class DtaBackendUtils {
     }
 
     /**
-     * Sends the configuration textfile uploaded by prof to the backend
+     * Sends the configuration textfile uploaded by prof to the backend.
      *
      * @param $assignment assignment this test-config belongs to
      * @param $file uploaded test-config
-     *
      * @return bool true if no error occurred
      */
     public static function sendtestconfigtobackend($assignment, $file): bool {
@@ -61,11 +76,10 @@ class DtaBackendUtils {
     }
 
     /**
-     * Sends sumbission config or archive to backend to be tested
+     * Sends sumbission config or archive to backend to be tested.
      *
      * @param $assignment assignment this submission is done for
      * @param $file submission config file or archive with submission
-     *
      * @return string json string with testresults or null on error
      */
     public static function sendsubmissiontobackend($assignment, $file): ?string {
@@ -87,6 +101,7 @@ class DtaBackendUtils {
     }
 
     /**
+     * Posts the given params to the given url and returns the response as a string.
      * @param string $url full url to request to
      * @param array $params parameters for http-request
      *

dta/utils/database.php

@@ -14,11 +14,22 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * persistence layer utility class
+ *
+ * @package assignsubmission_dta
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
+ */ 
 class DbUtils {
 
-    // Summary database table name.
+    /**
+     * Summary database table name.
+     */
     private const TABLE_SUMMARY = "assignsubmission_dta_summary";
-    // Result database table name.
+    /**
+     * Result database table name.
+     */
     private const TABLE_RESULT = "assignsubmission_dta_result";
 
     /**
@@ -77,9 +88,9 @@ class DbUtils {
      * save given result summary and single results to database
      * under given assignment and submission id
      *
-     * @param int assignmentid assigment this is submission is linked to
-     * @param int submissionid submission of this result
-     * @param DttResultSummary instance to persist
+     * @param $assignmentid assigment this is submission is linked to
+     * @param $submissionid submission of this result
+     * @param $summary instance to persist
      */
     public static function storeresultsummarytodatabase(
         int $assignmentid,

dta/utils/view.php

@@ -23,7 +23,7 @@
  */
 class view_submission_utils {
 
-    /** 
+    /**
      * Broadly used in logic, parametrized for easier change.
      */
     const COMPONENT_NAME = "assignsubmission_dta";
@@ -31,8 +31,8 @@ class view_submission_utils {
     /**
      * generates a short summary html
      *
-     * @param int assignmentid assignment
-     * @param int submissionid submission to create a report for
+     * @param $assignmentid assignment
+     * @param $submissionid submission to create a report for
      * @return string html
      */
     public static function generatesummaryhtml(
@@ -67,17 +67,18 @@ class view_submission_utils {
 
         $showncompetencies = explode(";", $summary->successfultestcompetencies);
         $overallcompetencies = explode(";", $summary->overalltestcompetencies);
-        
+
         $tmp = "";
         for ($index = 0, $size = count($showncompetencies); $index < $size; $index++) {
             $shown = $showncompetencies[$index];
             $comp = $overallcompetencies[$index];
             // If the competency was actually assessed by the assignment and tests, add a summary entry.
-            if($shown!="0") {
-                $tmp .= get_string("comp" . $index, self::COMPONENT_NAME) . " " . 100*floatval($shown)/floatval($comp) . "% " . "<br />";
+            if ($shown != "0") {
+                $tmp .= get_string("comp" . $index, self::COMPONENT_NAME) . 
+                " " . 100 * floatval($shown) / floatval($comp) . "% " . "<br />";
             }
         }
-        
+
         $html .= get_string("success_competencies", self::COMPONENT_NAME) . "<br />" . $tmp . "<br />";
 
         return html_writer::div($html, "dtaSubmissionSummary");
@@ -86,8 +87,8 @@ class view_submission_utils {
     /**
      * generates detailed view html
      *
-     * @param int assignmentid assignment
-     * @param int submissionid submission to create a report for
+     * @param $assignmentid assignment
+     * @param $submissionid submission to create a report for
      */
     public static function generatedetailhtml(
         int $assignmentid,
@@ -220,7 +221,7 @@ class view_submission_utils {
 
         // Add empty div for spacing between summary and compentency table.
         $html .= html_writer::empty_tag("div", ["class" => "dtaSpacer"]);
-        
+
         // Competency assessment table.
         $body = "";
         $tmp = "";
@@ -228,10 +229,10 @@ class view_submission_utils {
         $tmp .= html_writer::empty_tag("th", ["class" => "dtaTableHeader"]);
         $header = html_writer::tag("tr", $tmp, $tableheaderrowattributes);
         $header = html_writer::tag("thead", $header);
-        
+
         $showncompetencies = explode(";", $summary->successfultestcompetencies);
         $overallcompetencies = explode(";", $summary->overalltestcompetencies);
-        
+
         for ($index = 0, $size = count($overallcompetencies); $index < $size; $index++) {
             $comp = $overallcompetencies[$index];
             $shown = $showncompetencies[$index];
@@ -241,10 +242,10 @@ class view_submission_utils {
                 $resultrowattributes = $tablerowattributes;
                 $tmp = "";
                 $tmp .= html_writer::tag("td", get_string("comp" . $index, self::COMPONENT_NAME), $resultrowattributes);                
-                $tmp .= html_writer::tag("td", 100*floatval($shown)/floatval($comp) . "% " .
+                $tmp .= html_writer::tag("td", 100 * floatval($shown) / floatval($comp) . "% " .
                     "(" . $shown . " / " . $comp . ")", $resultrowattributes);
-                $tmp .= html_writer::tag("td", get_string("comp_expl" . $index, self::COMPONENT_NAME), $resultrowattributes);    
-                
+                $tmp .= html_writer::tag("td", get_string("comp_expl" . $index, self::COMPONENT_NAME), $resultrowattributes);
+
                 $body .= html_writer::tag("tr", $tmp, $resultrowattributes);
             }
         }
@@ -288,7 +289,7 @@ class view_submission_utils {
                 "td",
                 get_string("package_name", self::COMPONENT_NAME),
                 $attributes);
-                
+
             $tmp .= html_writer::tag(
                 "td",
                 $r->packagename,