added documentation comments

dta/db/upgrade.php

@@ -19,6 +19,7 @@
  *
  * @package   assignsubmission_dta
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
  */
 
 /**
@@ -28,6 +29,6 @@
  */
 function xmldb_assignsubmission_dta_upgrade($oldversion) {
     global $CFG;
-
+    // Currently no adjustments necessary for Moodle upgrades. Works without changes since the first MoJEC version.
     return true;
 }

dta/lang/en/assignsubmission_dta.php

@@ -19,6 +19,7 @@
  *
  * @package   assignsubmission_dta
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
  */
 
 // General.

dta/lib.php

@@ -19,6 +19,7 @@
  *
  * @package   assignsubmission_dta
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
  */
 
 /**

dta/locallib.php

@@ -30,13 +30,21 @@ 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.
+    /** 
+     * 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.
+    /** 
+     * Draft file area for dta tests to be uploaded by the teacher.
+     */
     const ASSIGNSUBMISSION_DTA_DRAFT_FILEAREA_TEST = "tests_draft_dta";
-    // File area for dta tests to be uploaded by the teacher.
+    /**
+     * File area for dta tests to be uploaded by the teacher.
+     */
     const ASSIGNSUBMISSION_DTA_FILEAREA_TEST = "tests_dta";
-    // File area for dta submission assignment.
+    /**
+     * File area for dta submission assignment.
+     */
     const ASSIGNSUBMISSION_DTA_FILEAREA_SUBMISSION = "submissions_dta";
 
     /**
@@ -304,7 +312,7 @@ class assign_submission_dta extends assign_submission_plugin {
     public function view_summary(stdClass $submission, & $showviewlink) {
         $showviewlink = true;
 
-        return ViewSubmissionUtils::generatesummaryhtml(
+        return view_submission_utils::generatesummaryhtml(
             $this->assignment->get_instance()->id,
             $submission->id
         );
@@ -317,7 +325,7 @@ class assign_submission_dta extends assign_submission_plugin {
      * @return string detailed results html
      */
     public function view(stdClass $submission) {
-        return ViewSubmissionUtils::generatedetailhtml(
+        return view_submission_utils::generatedetailhtml(
             $this->assignment->get_instance()->id,
             $submission->id
         );

dta/models/DtaResult.php

@@ -16,13 +16,33 @@
 
 defined('MOODLE_INTERNAL') || die();
 
+/**
+ * entity class for DTA submission plugin result
+ *
+ * @package assignsubmission_dta
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
+ */
 class DtaResult {
 
-    // Broadly used in logic, parametrized for easier change.
+    /** 
+     * Broadly used in logic, parametrized for easier change.
+     */
     const COMPONENT_NAME = "assignsubmission_dta";
 
+    /** 
+     * Package name of the test.
+     */
     public $packagename;
+    
+    /** 
+     * Unit name of the test.
+     */
     public $classname;
+    
+    /** 
+     * Name of the test.
+     */
     public $name;
 
     /**
@@ -35,16 +55,37 @@ class DtaResult {
      */
     public $state;
 
+    /** 
+     * Type of test failure if applicable, "" otherwise.
+     */
     public $failuretype;
+    
+    /** 
+     * Reason of test failure if applicable, "" otherwise.
+     */    
     public $failurereason;
+    
+    /** 
+     * Stack trace of test failure if applicable, "" otherwise.
+     */    
     public $stacktrace;
 
+    /** 
+     * Column number of compile failure if applicable, "" otherwise.
+     */    
     public $columnnumber;
+    /** 
+     * Line number of compile failure if applicable, "" otherwise.
+     */    
     public $linenumber;
+    /** 
+     * Position of compile failure if applicable, "" otherwise.
+     */    
     public $position;
 
     /**
-     * @return name of state like defined
+     * Returns the name of a state with the given number of display.
+     * @return name of state as defined
      */
     public static function getstatename(int $state): string {
         if ($state == 1) {
@@ -59,15 +100,40 @@ class DtaResult {
     }
 }
 
+/**
+ * entity class for DTA submission plugin result
+ *
+ * @package assignsubmission_dta
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
+ */
 class DtaResultSummary {
 
+    /** 
+     * Result timestamp for chronological ordering and deletion of previous results.
+     */    
     public $timestamp;
+    
+    /** 
+     * Global stack trace if applicable, "" otherwise.
+     */    
     public $globalstacktrace;
+    
+    /** 
+     * Successfully tested competencies according to tests and weights, "" otherwise.
+     */    
     public $successfultestcompetencies;
+    /** 
+     * Overall tested competencies according to tests and weights, "" otherwise.
+     */    
     public $overalltestcompetencies;
+    /** 
+     * 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
      * @return DtaResultSummary
      */
@@ -87,6 +153,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
      * @return array of DtaResult
      */
@@ -113,11 +180,17 @@ class DtaResultSummary {
         return $ret;
     }
 
+
+    /**
+     * Returns the number of detail results attached to the summary.
+     * @return int count of occurences
+     */
     public function resultcount(): int {
         return count($this->results);
     }
 
     /**
+     * Returns the number of detail results with the given state attached to the summary.
      * @param int $state state ordinal number
      * @return int count of occurences provided state has
      */
@@ -131,18 +204,34 @@ class DtaResultSummary {
         return $num;
     }
 
+    /**
+     * Returns the number of detail results with compilation errors attached to the summary.
+     * @return int count of occurences
+     */
     public function compilationerrorcount(): int {
         return $this->stateoccurencecount(3);
     }
 
+    /**
+     * Returns the number of detail results with test failures attached to the summary.
+     * @return int count of occurences
+     */
     public function failedcount(): int {
         return $this->stateoccurencecount(2);
     }
 
+    /**
+     * Returns the number of detail results with successful tests attached to the summary.
+     * @return int count of occurences
+     */
     public function successfulcount(): int {
         return $this->stateoccurencecount(1);
     }
 
+    /**
+     * Returns the number of detail results with an unknown result - mostly due to compile errors - attached to the summary.
+     * @return int count of occurences
+     */
     public function unknowncount(): int {
         return $this->stateoccurencecount(0);
     }

dta/settings.php

@@ -19,6 +19,7 @@
  *
  * @package   assignsubmission_dta
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
  */
 
 defined('MOODLE_INTERNAL') || die();

dta/utils/view.php

@@ -14,9 +14,18 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-class ViewSubmissionUtils {
-
-    // Broadly used in logic, parametrized for easier change.
+/**
+ * utility class for DTA submission plugin result display
+ *
+ * @package assignsubmission_dta
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
+ */
+class view_submission_utils {
+
+    /** 
+     * Broadly used in logic, parametrized for easier change.
+     */
     const COMPONENT_NAME = "assignsubmission_dta";
 
     /**
@@ -60,16 +69,16 @@ class ViewSubmissionUtils {
         $overallcompetencies = explode(";", $summary->overalltestcompetencies);
         
         $tmp = "";
-        for ($index=0, $size=count($showncompetencies); $index<$size; $index++) {
-            $shown=$showncompetencies[$index];
-            $comp=$overallcompetencies[$index];
+        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 />";
             }
         }
         
-        $html .= get_string("success_competencies", self::COMPONENT_NAME) . $tmp . "<br />";
+        $html .= get_string("success_competencies", self::COMPONENT_NAME) . "<br />" . $tmp . "<br />";
 
         return html_writer::div($html, "dtaSubmissionSummary");
     }
@@ -223,11 +232,11 @@ class ViewSubmissionUtils {
         $showncompetencies = explode(";", $summary->successfultestcompetencies);
         $overallcompetencies = explode(";", $summary->overalltestcompetencies);
         
-        for ($index=0, $size=count($overallcompetencies); $index<$size; $index++) {
-            $comp=$overallcompetencies[$index];
-            $shown=$showncompetencies[$index];
+        for ($index = 0, $size = count($overallcompetencies); $index < $size; $index++) {
+            $comp = $overallcompetencies[$index];
+            $shown = $showncompetencies[$index];
             // If the competency was actually assessed by the assignment and tests, add a row in the table.
-            if($comp!="0") {
+            if($comp != "0") {
                 // New copy of base attributes array.
                 $resultrowattributes = $tablerowattributes;
                 $tmp = "";

dta/version.php

@@ -19,6 +19,7 @@
  *
  * @package    assignsubmission_dta
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright Gero Lueckemeyer and student project teams
  */
 
 defined('MOODLE_INTERNAL') || die();