From ffe02865d24f9a5ccff4ccff41355612a34dd624 Mon Sep 17 00:00:00 2001
From: emkael <emkael@tlen.pl>
Date: Thu, 13 Feb 2025 23:37:28 +0100
Subject: Elaborate comments on check_parameters and parse_parameters

---
 http/api-inc.php | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/http/api-inc.php b/http/api-inc.php
index b33b9e0..ca8e0de 100644
--- a/http/api-inc.php
+++ b/http/api-inc.php
@@ -186,6 +186,16 @@ class ApiPkl {
         }
     }
 
+    /*
+     * This shouldn't alter any parameters, just validate them.
+     * The exception is when a new version no longer marks parameter
+       as mandatory, and assumes some default/derived values.
+     * Or when a parameter value marks other parameters as ignored,
+       meaning these parameters should never reach parse_parameters().
+     * Only then check_parameters should alter the provided
+       parameter list, which is also why it's still passed around
+       as an argument->return value.
+     */
     function check_parameters($parameters) {
         $this->ensure_parameters($parameters, array('type', 'contestants'));
         $this->check_values($parameters, array(
@@ -262,6 +272,17 @@ class ApiPkl {
         return $parameters;
     }
 
+    /*
+     * This parses the parameters, transforms them and fills missing,
+       derivable data.
+     * When overriding, be careful when to use the original parameter list
+       from method argument, and when to use parameter list parsed
+       by parent::parse_parameters.
+     * Good guideline is that when API version introduces new parameter,
+       it must be parsed from method argument (as parent wouldn't parse it),
+       and all other times, the return value of parent::parse_parameters
+       is likely to be used.
+     */
     function parse_parameters($parameters) {
         $return = array();
         $return['type'] = intval($parameters['type']);
-- 
cgit v1.2.3