Elaborate comments on check_parameters and parse_parameters

1 files changed, 21 insertions, 0 deletions

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']);