docs: improve PHPDoc comments

Author: kenjis

system/API/ResponseTrait.php

@@ -64,10 +64,11 @@ trait ResponseTrait
 
     /**
      * How to format the response data.
-     * Either 'json' or 'xml'. If blank will be
-     * determined through content negotiation.
+     * Either 'json' or 'xml'. If null is set, it will be determined through
+     * content negotiation.
      *
-     * @var string
+     * @var string|null
+     * @phpstan-var 'json'|'xml'|null
      */
     protected $format = 'json';
 
@@ -294,7 +295,7 @@ protected function failServerError(string $description = 'Internal Server Error'
     // --------------------------------------------------------------------
 
     /**
-     * Handles formatting a response. Currently makes some heavy assumptions
+     * Handles formatting a response. Currently, makes some heavy assumptions
      * and needs updating! :)
      *
      * @param array|string|null $data
@@ -350,6 +351,9 @@ protected function format($data = null)
     /**
      * Sets the format the response should be in.
      *
+     * @param         string|null  $format Response format
+     * @phpstan-param 'json'|'xml' $format
+     *
      * @return $this
      */
     protected function setResponseFormat(?string $format = null)

system/RESTful/ResourceController.php

@@ -106,7 +106,7 @@ public function delete($id = null)
     /**
      * Set/change the expected response representation for returned objects
      *
-     * @param         string       $format json/xml
+     * @param         string       $format Response format
      * @phpstan-param 'json'|'xml' $format
      *
      * @return void