made TODOs more future-proof

Author: eceltov

app/helpers/Swagger/AnnotationData.php

@@ -38,7 +38,7 @@ private function getBodyAnnotation(): string | null
             return null;
         }
 
-        ///TODO: only supports JSON
+        ///TODO: The swagger generator only supports JSON due to the hardcoded mediaType below
         $head = '@OA\RequestBody(@OA\MediaType(mediaType="application/json",@OA\Schema';
         $body = new ParenthesesBuilder();
 
@@ -72,7 +72,8 @@ public function toSwaggerAnnotations(string $route)
             $body->addValue($jsonProperties);
         }
 
-        ///TODO: placeholder
+        ///TODO: A placeholder for the response type. This has to be replaced with the autogenerated meta-view
+        /// response data structure in the future.
         $body->addValue('@OA\Response(response="200",description="The data")');
         return $httpMethodAnnotation . $body->toString();
     }

app/helpers/Swagger/AnnotationParameterData.php

@@ -76,10 +76,11 @@ private function getSwaggerType(): string
             }
 
             if (self::$typeMap[$typename] === null) {
-              ///TODO: return the commented exception
+                ///TODO: Return the commented exception below once the meta-view formats are implemented.
+                /// This detaults to strings because custom types like 'email' are not supported yet.
                 return 'string';
             }
-              //throw new \InvalidArgumentException("Error in getSwaggerType: Unknown typename: {$typename}");
+            //throw new \InvalidArgumentException("Error in getSwaggerType: Unknown typename: {$typename}");
 
             $type = self::$typeMap[$typename];
         }
@@ -120,7 +121,7 @@ public function toPropertyAnnotation(): string
         $head = "@OA\\Property";
         $body = new ParenthesesBuilder();
 
-        ///TODO: handle nullability
+        ///TODO: Once the meta-view formats are implemented, add support for property nullability here.
         $body->addKeyValue("property", $this->name);
         $body->addKeyValue("type", $this->getSwaggerType());
         return $head . $body->toString();