Update comments and doc blocks

Author: na2axl

src/WaterPipe/HTTP/Header.php

@@ -44,17 +44,35 @@ abstract class Header implements \ArrayAccess, \SeekableIterator, \JsonSerializa
      */
     private $_position = 0;
 
+    /**
+     * Create or change the value of an HTTP header field.
+     *
+     * @param string $name The name of the header field
+     * @param string $value The value of the header field
+     */
     public function setField(string $name, string $value)
     {
         $this->_fields[strtolower($name)] = $value;
     }
 
+    /**
+     * Returns the value of an HTTP heade field.
+     *
+     * @param string $name The name of the header field
+     *
+     * @return string The value of the header field.
+     */
     public function getField(string $name): string
     {
         $name = strtolower($name);
         return array_key_exists($name, $this->_fields) ? $this->_fields[$name] : "";
     }
 
+    /**
+     * Returns the set of headers in the HTTP format.
+     *
+     * @return array
+     */
     public function toArray(): array
     {
         $raw = array();
@@ -71,7 +89,7 @@ public function toArray(): array
      * @param mixed $offset <p>
      * An offset to check for.
      * </p>
-     * @return boolean true on success or false on failure.
+     * @return bool true on success or false on failure.
      * </p>
      * <p>
      * The return value will be casted to boolean if non-boolean was returned.
@@ -173,7 +191,7 @@ public function key()
     /**
      * Checks if current position is valid
      * @link http://php.net/manual/en/iterator.valid.php
-     * @return boolean The return value will be casted to boolean and then evaluated.
+     * @return bool The return value will be casted to boolean and then evaluated.
      * Returns true on success or false on failure.
      * @since 5.0.0
      */
@@ -243,4 +261,4 @@ public function jsonSerialize()
     {
         return json_encode($this->_fields);
     }
-}
+}

src/WaterPipe/HTTP/Request/Request.php

@@ -84,6 +84,8 @@ public function __construct()
     }
 
     /**
+     * Returns the request method.
+     *
      * @return int
      */
     public function getMethod(): int
@@ -92,6 +94,8 @@ public function getMethod(): int
     }
 
     /**
+     * Sets the request method.
+     *
      * @param int $type
      */
     public function setMethod(int $type): void
@@ -100,6 +104,8 @@ public function setMethod(int $type): void
     }
 
     /**
+     * Returns the set of request parameters from query string.
+     *
      * @return RequestData|null
      */
     public function getParams(): ?RequestData
@@ -108,6 +114,8 @@ public function getParams(): ?RequestData
     }
 
     /**
+     * Sets the request parameters.
+     *
      * @param RequestData $params
      */
     public function setParams(RequestData $params): void
@@ -116,6 +124,8 @@ public function setParams(RequestData $params): void
     }
 
     /**
+     * Returns the request body.
+     *
      * @return RequestData
      */
     public function getBody(): RequestData
@@ -124,6 +134,8 @@ public function getBody(): RequestData
     }
 
     /**
+     * Sets the request body.
+     *
      * @param RequestData $body
      */
     public function setBody(RequestData $body): void
@@ -132,6 +144,8 @@ public function setBody(RequestData $body): void
     }
 
     /**
+     * Returns the set of cookies attached to the request.
+     *
      * @return RequestData
      */
     public function getCookies(): RequestData
@@ -140,6 +154,8 @@ public function getCookies(): RequestData
     }
 
     /**
+     * Sets the cookies attached to the request.
+     *
      * @param RequestData $cookies
      */
     public function setCookies(RequestData $cookies): void
@@ -148,6 +164,8 @@ public function setCookies(RequestData $cookies): void
     }
 
     /**
+     * Returns the request headers.
+     *
      * @return RequestHeader
      */
     public function getHeader(): RequestHeader
@@ -156,6 +174,8 @@ public function getHeader(): RequestHeader
     }
 
     /**
+     * Set the request headers.
+     *
      * @param RequestHeader $header
      */
     public function setHeader(RequestHeader $header): void
@@ -257,4 +277,4 @@ public static function &capture(): Request
     {
         return Router::getInstance()->build()->getRequest();
     }
-}
+}

src/WaterPipe/HTTP/Request/RequestMethod.php

@@ -34,6 +34,7 @@
 
 /**
  * Class RequestMethod
+ *
  * @package  WaterPipe
  * @category Enumerations
  */

src/WaterPipe/HTTP/Request/RequestUri.php

@@ -226,7 +226,7 @@ public static function makeUri(...$parts)
      * @param mixed $offset <p>
      * An offset to check for.
      * </p>
-     * @return boolean true on success or false on failure.
+     * @return bool true on success or false on failure.
      * </p>
      * <p>
      * The return value will be casted to boolean if non-boolean was returned.

src/WaterPipe/HTTP/Response/ResponseStatus.php

@@ -151,7 +151,7 @@ class ResponseStatus
     );
 
     /**
-     * @var integer
+     * @var int
      */
     private $_code;
 
@@ -186,6 +186,8 @@ public function __toString()
     }
 
     /**
+     * Returns the response status code.
+     *
      * @return int
      */
     public function getCode(): int
@@ -194,6 +196,8 @@ public function getCode(): int
     }
 
     /**
+     * Returns the response status description.
+     *
      * @return string
      */
     public function getDescription(): string
@@ -202,13 +206,21 @@ public function getDescription(): string
     }
 
     /**
+     * Returns the list of registered status codes and descriptions
+     *
      * @return array
      */
     public static function getRegistry(): array
     {
         return self::$_registry;
     }
 
+    /**
+     * Add a new response status code in the registry
+     *
+     * @param int $code The response status code
+     * @param string $description The response status description
+     */
     public static function registerStatusCode(int $code, string $description)
     {
         self::$_registry[$code] = $description;

src/WaterPipe/Routing/Middleware/Middleware.php

@@ -37,7 +37,17 @@
 
 abstract class Middleware
 {
+    /**
+     * Executes an action just before the execution of the request.
+     *
+     * @param Request &$request The request wich will be executed.
+     */
     public abstract function beforeExecute(Request &$request);
 
+    /**
+     * Executes an action just before send the response.
+     *
+     * @param Response &$response The response which will be sent.
+     */
     public abstract function beforeSend(Response &$response);
-}
+}

src/WaterPipe/Routing/Route.php

@@ -67,20 +67,42 @@ public function __construct(string $uri)
     }
 
     /**
+     * Returns the URI handled by this route.
+     *
      * @return string
      */
     public function getUri(): string
     {
         return $this->_uri;
     }
 
+    /**
+     * Execute an action when any kind of request method
+     * is sent to this route.
+     */
     public abstract function request();
 
+    /**
+     * Execute an action when a GET request method
+     * is sent to this route.
+     */
     public abstract function get();
 
+    /**
+     * Execute an action when a POST request method
+     * is sent to this route.
+     */
     public abstract function post();
 
+    /**
+     * Execute an action when a PUT request method
+     * is sent to this route.
+     */
     public abstract function put();
 
+    /**
+     * Execute an action when a DELETE request method
+     * is sent to this route.
+     */
     public abstract function delete();
-}
+}

src/WaterPipe/Routing/RouteAction.php

@@ -58,5 +58,8 @@ public function __construct()
         $this->_response = new Response();
     }
 
+    /**
+     * Executes the action.
+     */
     public abstract function execute();
-}
+}

src/WaterPipe/Routing/Router.php

@@ -50,13 +50,24 @@ class Router
      */
     private $_request;
 
+    /**
+     * @var bool
+     */
     private $_built = false;
 
+    /**
+     * Router constructor
+     */
     private function __construct()
     {
         $this->_request = new Request();
     }
 
+    /**
+     * Returns the unique instance of the Router.
+     *
+     * @return self
+     */
     public static function &getInstance()
     {
         static $instance;
@@ -66,6 +77,11 @@ public static function &getInstance()
         return $instance[0];
     }
 
+    /**
+     * Builds the router and capture the request.
+     *
+     * @return self
+     */
     public function build(): self
     {
         if (!$this->_built) {
@@ -79,6 +95,9 @@ public function build(): self
         return $this;
     }
 
+    /**
+     * Detects the current request method.
+     */
     private function _detectMethod()
     {
         if (isset($_SERVER["REQUEST_METHOD"])) {
@@ -108,6 +127,9 @@ private function _detectMethod()
         }
     }
 
+    /**
+     * Detects the current request URI.
+     */
     private function _detectUri()
     {
         $config = WaterPipeConfig::get();
@@ -190,6 +212,9 @@ private function _detectUri()
         $this->_request->uri->setUri(str_replace(array('//', '../'), '/', trim($uri)));
     }
 
+    /**
+     * Detects the current request headers.
+     */
     private function _detectHeaders()
     {
         if (is_array($headers = getallheaders())) {
@@ -204,6 +229,8 @@ private function _detectHeaders()
     }
 
     /**
+     * Checks if the router is built or not.
+     *
      * @return bool
      */
     public function isBuilt(): bool
@@ -212,10 +239,13 @@ public function isBuilt(): bool
     }
 
     /**
+     * Returns the captured request at the build time
+     * of the router.
+     *
      * @return Request
      */
     public function &getRequest(): Request
     {
         return $this->_request;
     }
-}
+}