From 91aaaa998d93c8b3d3709671326541d88e97087a Mon Sep 17 00:00:00 2001
From: "John Paul E. Balandan, CPA" <paulbalandan@gmail.com>
Date: Sun, 12 Jul 2020 21:58:46 +0800
Subject: [PATCH] Fix PHPDocs for Router

---
 .../Router/Exceptions/RedirectException.php   | 45 ++++++++++++++-
 system/Router/Exceptions/RouterException.php  | 55 ++++++++++++++++++-
 system/Router/RouteCollection.php             | 54 +++++++++---------
 3 files changed, 126 insertions(+), 28 deletions(-)

diff --git a/system/Router/Exceptions/RedirectException.php b/system/Router/Exceptions/RedirectException.php
index 5c3f695570cd..611420766a47 100644
--- a/system/Router/Exceptions/RedirectException.php
+++ b/system/Router/Exceptions/RedirectException.php
@@ -1,12 +1,53 @@
 <?php
 
+/**
+ * CodeIgniter
+ *
+ * An open source application development framework for PHP
+ *
+ * This content is released under the MIT License (MIT)
+ *
+ * Copyright (c) 2014-2019 British Columbia Institute of Technology
+ * Copyright (c) 2019-2020 CodeIgniter Foundation
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @package    CodeIgniter
+ * @author     CodeIgniter Dev Team
+ * @copyright  2019-2020 CodeIgniter Foundation
+ * @license    https://opensource.org/licenses/MIT	MIT License
+ * @link       https://codeigniter.com
+ * @since      Version 4.0.0
+ * @filesource
+ */
+
 namespace CodeIgniter\Router\Exceptions;
 
 /**
- * Redirect exception
+ * RedirectException
  */
-
 class RedirectException extends \Exception
 {
+	/**
+	 * Status code for redirects
+	 *
+	 * @var integer
+	 */
 	protected $code = 302;
 }
diff --git a/system/Router/Exceptions/RouterException.php b/system/Router/Exceptions/RouterException.php
index 7117c55f8fbd..b58d64eba48e 100644
--- a/system/Router/Exceptions/RouterException.php
+++ b/system/Router/Exceptions/RouterException.php
@@ -1,15 +1,68 @@
-<?php namespace CodeIgniter\Router\Exceptions;
+<?php
+
+/**
+ * CodeIgniter
+ *
+ * An open source application development framework for PHP
+ *
+ * This content is released under the MIT License (MIT)
+ *
+ * Copyright (c) 2014-2019 British Columbia Institute of Technology
+ * Copyright (c) 2019-2020 CodeIgniter Foundation
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @package    CodeIgniter
+ * @author     CodeIgniter Dev Team
+ * @copyright  2019-2020 CodeIgniter Foundation
+ * @license    https://opensource.org/licenses/MIT	MIT License
+ * @link       https://codeigniter.com
+ * @since      Version 4.0.0
+ * @filesource
+ */
+
+namespace CodeIgniter\Router\Exceptions;
 
 use CodeIgniter\Exceptions\ExceptionInterface;
 use CodeIgniter\Exceptions\FrameworkException;
 
+/**
+ * RouterException
+ */
 class RouterException extends FrameworkException implements ExceptionInterface
 {
+	/**
+	 * Thrown when the actual parameter type does not match
+	 * the expected types.
+	 *
+	 * @return \CodeIgniter\Router\Exceptions\RouterException
+	 */
 	public static function forInvalidParameterType()
 	{
 		return new static(lang('Router.invalidParameterType'));
 	}
 
+	/**
+	 * Thrown when a default route is not set.
+	 *
+	 * @return \CodeIgniter\Router\Exceptions\RouterException
+	 */
 	public static function forMissingDefaultRoute()
 	{
 		return new static(lang('Router.missingDefaultRoute'));
diff --git a/system/Router/RouteCollection.php b/system/Router/RouteCollection.php
index baf498f0e47d..bce96c01cc75 100644
--- a/system/Router/RouteCollection.php
+++ b/system/Router/RouteCollection.php
@@ -1,4 +1,5 @@
 <?php
+
 /**
  * CodeIgniter
  *
@@ -229,8 +230,8 @@ class RouteCollection implements RouteCollectionInterface
 	/**
 	 * Constructor
 	 *
-	 * @param FileLocator     $locator
-	 * @param \Config\Modules $moduleConfig
+	 * @param \CodeIgniter\Autoloader\FileLocator $locator
+	 * @param \Config\Modules                     $moduleConfig
 	 */
 	public function __construct(FileLocator $locator, $moduleConfig)
 	{
@@ -271,7 +272,7 @@ public function addPlaceholder($placeholder, string $pattern = null): RouteColle
 	 * Sets the default namespace to use for Controllers when no other
 	 * namespace has been specified.
 	 *
-	 * @param $value
+	 * @param string $value
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -289,7 +290,7 @@ public function setDefaultNamespace(string $value): RouteCollectionInterface
 	 * Sets the default controller to use when no other controller has been
 	 * specified.
 	 *
-	 * @param $value
+	 * @param string $value
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -306,7 +307,7 @@ public function setDefaultController(string $value): RouteCollectionInterface
 	 * Sets the default method to call on the controller when no other
 	 * method has been set in the route.
 	 *
-	 * @param $value
+	 * @param string $value
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -622,7 +623,7 @@ public function map(array $routes = [], array $options = null): RouteCollectionI
 	 *
 	 * @param string       $from
 	 * @param array|string $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return RouteCollectionInterface
 	 */
@@ -653,7 +654,7 @@ public function addRedirect(string $from, string $to, int $status = 302)
 		{
 			$to = $this->routes['*'][$to]['route'];
 		}
-		else if (array_key_exists($to, $this->routes['get']))
+		elseif (array_key_exists($to, $this->routes['get']))
 		{
 			$to = $this->routes['get'][$to]['route'];
 		}
@@ -724,8 +725,8 @@ public function getRedirectCode(string $from): int
 	 *            $route->resource('users');
 	 *     });
 	 *
-	 * @param string $name The name to group/prefix the routes with.
-	 * @param $params
+	 * @param string $name      The name to group/prefix the routes with.
+	 * @param array  ...$params
 	 *
 	 * @return void
 	 */
@@ -795,8 +796,8 @@ public function group(string $name, ...$params)
 	 *      POST		/photos/{id}/delete delete
 	 *      POST        /photos/{id}        update
 	 *
-	 * @param string $name    The name of the resource/controller to route to.
-	 * @param array  $options An list of possible ways to customize the routing.
+	 * @param string     $name    The name of the resource/controller to route to.
+	 * @param array|null $options An list of possible ways to customize the routing.
 	 *
 	 * @return RouteCollectionInterface
 	 */
@@ -909,8 +910,8 @@ public function resource(string $name, array $options = null): RouteCollectionIn
 	 *      GET         /photos/remove/{id} remove          show a form to confirm deletion of a specific photo object
 	 *      POST        /photos/delete/{id} delete          deleting the specified photo object
 	 *
-	 * @param string $name    The name of the controller to route to.
-	 * @param array  $options An list of possible ways to customize the routing.
+	 * @param string     $name    The name of the controller to route to.
+	 * @param array|null $options An list of possible ways to customize the routing.
 	 *
 	 * @return RouteCollectionInterface
 	 */
@@ -1009,7 +1010,7 @@ public function presenter(string $name, array $options = null): RouteCollectionI
 	 * @param array        $verbs
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1032,7 +1033,7 @@ public function match(array $verbs = [], string $from, $to, array $options = nul
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1050,7 +1051,7 @@ public function get(string $from, $to, array $options = null): RouteCollectionIn
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1068,7 +1069,7 @@ public function post(string $from, $to, array $options = null): RouteCollectionI
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1086,7 +1087,7 @@ public function put(string $from, $to, array $options = null): RouteCollectionIn
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1104,7 +1105,7 @@ public function delete(string $from, $to, array $options = null): RouteCollectio
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1122,7 +1123,7 @@ public function head(string $from, $to, array $options = null): RouteCollectionI
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1140,7 +1141,7 @@ public function patch(string $from, $to, array $options = null): RouteCollection
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1158,7 +1159,7 @@ public function options(string $from, $to, array $options = null): RouteCollecti
 	 *
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 *
 	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
@@ -1177,7 +1178,7 @@ public function cli(string $from, $to, array $options = null): RouteCollectionIn
 	 * @param string   $env
 	 * @param \Closure $callback
 	 *
-	 * @return RouteCollectionInterface
+	 * @return \CodeIgniter\Router\RouteCollectionInterface
 	 */
 	public function environment(string $env, \Closure $callback): RouteCollectionInterface
 	{
@@ -1192,7 +1193,7 @@ public function environment(string $env, \Closure $callback): RouteCollectionInt
 	//--------------------------------------------------------------------
 
 	/**
-	 * Attempts to look up a route based on it's destination.
+	 * Attempts to look up a route based on its destination.
 	 *
 	 * If a route exists:
 	 *
@@ -1327,6 +1328,7 @@ public function getFilterForRoute(string $search): string
 	 * @param array|null $params
 	 *
 	 * @return string
+	 * @throws \CodeIgniter\Router\Exceptions\RouterException
 	 */
 	protected function fillRouteParams(string $from, array $params = null): string
 	{
@@ -1369,7 +1371,7 @@ protected function fillRouteParams(string $from, array $params = null): string
 	 * @param string       $verb
 	 * @param string       $from
 	 * @param string|array $to
-	 * @param array        $options
+	 * @param array|null   $options
 	 */
 	protected function create(string $verb, string $from, $to, array $options = null)
 	{
@@ -1526,6 +1528,8 @@ private function checkSubdomains($subdomains): bool
 	 *
 	 * It's especially not perfect since it's possible to register a domain
 	 * with a period (.) as part of the domain name.
+	 *
+	 * @return mixed
 	 */
 	private function determineCurrentSubdomain()
 	{