PHPDoc documentation

classes/completion.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/>.
 /**
- *
+ * Completion model
  * @package    local_treestudyplan
  * @copyright  2023 P.M. Kuipers
  * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -25,15 +25,29 @@ defined('MOODLE_INTERNAL') || die();
 
 require_once($CFG->libdir.'/externallib.php');
 
+/**
+ * Model of different completion states
+ */
 class completion {
+    /** @var int */
     public const FAILED = -1;
+    /** @var int */
     public const INCOMPLETE = 0;
+    /** @var int */
     public const PENDING = 1;
+    /** @var int */
     public const PROGRESS = 2;
+    /** @var int */
     public const COMPLETED = 3;
+    /** @var int */
     public const GOOD = 4;
+    /** @var int */
     public const EXCELLENT = 5;
 
+    /**
+     * Map of completion state constants to string labels
+     * @var array
+     */
     private const LABELS = [
         self::FAILED     => 'failed',
         self::INCOMPLETE => 'incomplete',
@@ -44,6 +58,11 @@ class completion {
         self::EXCELLENT  => 'excellent',
     ];
 
+    /**
+     * Convert completion state to equivalent text label
+     * @param int $completion
+     * @return string
+     */
     public static function label($completion) {
         if (array_key_exists($completion, self::LABELS)) {
             return self::LABELS[$completion];
@@ -52,12 +71,22 @@ class completion {
         }
     }
 
+    /**
+     * Webservice structure for basic info
+     * @param int $value Webservice requirement constant
+     * @return \external_description Webservice output structure
+     */
     public static function structure($value = VALUE_REQUIRED) {
         return new \external_value( PARAM_TEXT,
                                     'completion state (failed|incomplete|pending|progress|completed|good|excellent)',
                                     $value);
     }
 
+    /**
+     * Count how many times each state occurs in a given array of completion states
+     * @param int[] $states The array of completion states
+     * @return array of state counts
+     */
     public static function count_states(array $states) {
         // Initialize result array.
         $statecount = [];