docs: add missing PHPdocs

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)),

classes/attempt_ui/question_ui_renderer.php

@@ -588,6 +588,22 @@ 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.
+     *
+     * At first glance, this function seems to be more suited to be placed in
+     * {@see question_ui_metadata_extractor}. It is here for two reasons:
+     * - The {@see \qtype_questionpy_renderer} uses the render warnings when it also renders the UI. The metadata
+     *   extractor is used in other methods.
+     * - While we should discourage it, it is possible for inputs to be inside `qpy:if-role` or `qpy:feedback`
+     *   elements. {@see question_ui_metadata_extractor} doesn't resolve those.
+     *
+     * @return array
+     * @see check_for_unknown_options
+     */
     private function extract_available_options(): array {
         $optionsbyname = [];
 
@@ -642,6 +658,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);
 

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,

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());