From aa0d1b8f871c7a83fda98e84cbf08e8f196b1b97 Mon Sep 17 00:00:00 2001
From: Maximilian Haye <m.haye@tu-berlin.de>
Date: Wed, 11 Dec 2024 15:33:21 +0100
Subject: [PATCH] docs: add missing PHPdocs

---
 classes/attempt_ui/invalid_option_warning.php | 26 ++++++++++++++++++-
 classes/attempt_ui/question_ui_renderer.php   | 16 ++++++++++++
 classes/attempt_ui/render_result.php          | 14 ++++++++++
 classes/utils.php                             |  9 +++++++
 4 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/classes/attempt_ui/invalid_option_warning.php b/classes/attempt_ui/invalid_option_warning.php
index dc6c105..bf6c69c 100644
--- a/classes/attempt_ui/invalid_option_warning.php
+++ b/classes/attempt_ui/invalid_option_warning.php
@@ -19,19 +19,43 @@
 use coding_exception;
 use html_writer;
 
+/**
+ * The last response has fields set to values which don't seem to be available anymore.
+ *
+ * @package    qtype_questionpy
+ * @author     Maximilian Haye
+ * @copyright  2024 TU Berlin, innoCampus {@link https://www.questionpy.org}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class invalid_option_warning {
+    /**
+     * Trivial constructor.
+     *
+     * @param string $name name of the input field in question
+     * @param string $value value from the last response, for which no option was found in the UI
+     * @param array $availablevalues the available options present in the UI
+     */
     public function __construct(
+        /** @var string $name name of the input field in question */
         public string $name,
+        /** @var string $value value from the last response, for which no option was found in the UI */
         public string $value,
+        /** @var array $availablevalues the available options present in the UI */
         public array $availablevalues
     ) {
     }
 
     /**
+     * Return a localized string describing this warning to humans. Name and values are escaped.
+     *
+     * @return string
      * @throws coding_exception
      */
     public function localize(): string {
-        $availablevaluesstr = implode(', ', array_map(fn($value) => html_writer::tag('code', format_string($value)), $this->availablevalues));
+        $availablevaluesstr = implode(', ', array_map(
+            fn($value) => html_writer::tag('code', format_string($value)),
+            $this->availablevalues
+        ));
 
         return get_string('render_warning_invalid_value', 'qtype_questionpy', [
             'name' => html_writer::tag('code', format_string($this->name)),
diff --git a/classes/attempt_ui/question_ui_renderer.php b/classes/attempt_ui/question_ui_renderer.php
index 5727557..13de02a 100644
--- a/classes/attempt_ui/question_ui_renderer.php
+++ b/classes/attempt_ui/question_ui_renderer.php
@@ -588,6 +588,15 @@ function (array $match) use ($question) {
         );
     }
 
+    /**
+     * For all selects, checkboxes and radios in the UI, collects the available option values.
+     *
+     * This can be opted-out of by setting `qpy:warn-on-unknown-option` on the input element. In the case of checkboxes
+     * and radios, any element having the attribute will exclude all inputs with the same name.
+     *
+     * @return array
+     * @see check_for_unknown_options
+     */
     private function extract_available_options(): array {
         $optionsbyname = [];
 
@@ -642,6 +651,13 @@ private function extract_available_options(): array {
         return $optionsbyname;
     }
 
+    /**
+     * Checks if the last response contains values which are invalid.
+     *
+     * @param array $availableoptionsbyname
+     * @return array
+     * @see extract_available_options
+     */
     private function check_for_unknown_options(array $availableoptionsbyname): array {
         $response = utils::get_last_response($this->attempt);
 
diff --git a/classes/attempt_ui/render_result.php b/classes/attempt_ui/render_result.php
index aa3b771..e140d2f 100644
--- a/classes/attempt_ui/render_result.php
+++ b/classes/attempt_ui/render_result.php
@@ -16,7 +16,21 @@
 
 namespace qtype_questionpy\attempt_ui;
 
+/**
+ * Result from {@see question_ui_renderer::render()}: The HTML and possibly warnings.
+ *
+ * @package    qtype_questionpy
+ * @author     Maximilian Haye
+ * @copyright  2024 TU Berlin, innoCampus {@link https://www.questionpy.org}
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class render_result {
+    /**
+     * Initialize a new render result.
+     *
+     * @param string $html
+     * @param array $warnings
+     */
     public function __construct(
         /** @var string $html */
         public string $html,
diff --git a/classes/utils.php b/classes/utils.php
index 7b0eea1..40d8877 100644
--- a/classes/utils.php
+++ b/classes/utils.php
@@ -132,6 +132,15 @@ public static function filter_for_response(array $qtvars): array {
         );
     }
 
+    /**
+     * Gets the last response submitted in the given attempt, or an empty array if no response has been submitted yet.
+     *
+     * The last response is the qt data of the last step which has {@see constants::QT_VAR_RESPONSE_MARKER} set, to
+     * which {@see utils::filter_for_response} is applied.
+     *
+     * @param question_attempt $qa
+     * @return array
+     */
     public static function get_last_response(question_attempt $qa): array {
         $step = $qa->get_last_step_with_qt_var(constants::QT_VAR_RESPONSE_MARKER);
         return self::filter_for_response($step->get_qt_data());