Add missing doc blocks and rename methods to be more consistent.

The feature is no longer called middleware, instead continue using
dispatcher filters. We can't really call this feature middleware as it
acts very differently from middleware in other frameworks.

src/Routing/Dispatcher.php

@@ -1,10 +1,5 @@
 <?php
 /**
- * Dispatcher takes the URL information, parses it for parameters and
- * tells the involved controllers what to do.
- *
- * This is the heart of CakePHP's operation.
- *
  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  *
@@ -26,6 +21,7 @@ use Cake\Core\Configure;
 use Cake\Core\Plugin;
 use Cake\Error\Exception;
 use Cake\Event\Event;
+use Cake\Event\EventListener;
 use Cake\Event\EventManager;
 use Cake\Network\Request;
 use Cake\Network\Response;
@@ -47,11 +43,11 @@ class Dispatcher {
 	protected $_eventManager;
 
 /**
- * Connected middleware objects
+ * Connected filter objects
  *
  * @var array
  */
-	protected $_middleware = [];
+	protected $_filters = [];
 
 /**
  * Constructor.
@@ -223,13 +219,28 @@ class Dispatcher {
 		return false;
 	}
 
-	public function add($filter) {
-		$this->_middleware[] = $filter;
+/**
+ * Add a filter to this dispatcher.
+ *
+ * The added filter will be attached to the event manager used
+ * by this dispatcher.
+ *
+ * @param \Cake\Event\EventListener $filter The filter to connect. Can be
+ *   any EventListener. Typically an instance of \Cake\Routing\DispatcherFilter.
+ * @return void
+ */
+	public function addFilter(EventListener $filter) {
+		$this->_filters[] = $filter;
 		$this->getEventManager()->attach($filter);
 	}
 
-	public function middleware() {
-		return $this->_middleware;
+/**
+ * Get the list of connected filters.
+ *
+ * @return array
+ */
+	public function filters() {
+		return $this->_filters;
 	}
 
 }

src/Routing/DispatcherFactory.php

@@ -74,7 +74,7 @@ class DispatcherFactory {
 	public static function create() {
 		$dispatcher = new Dispatcher();
 		foreach (static::$_stack as $middleware) {
-			$dispatcher->add($middleware);
+			$dispatcher->addFilter($middleware);
 		}
 		return $dispatcher;
 	}

src/Routing/DispatcherFilter.php

@@ -24,6 +24,8 @@ use Cake\Event\EventListener;
  * event listener with the ability to alter the request or response as needed before it is handled
  * by a controller or after the response body has already been built.
  *
+ * Subclasses of this class use a class naming convention having a `Filter` suffix.
+ *
  * ### Limiting filters to specific paths
  *
  * By using the `for` option you can limit with request paths a filter is applied to.
@@ -31,10 +33,10 @@ use Cake\Event\EventListener;
  * example, if you only wanted a filter applied to blog requests you could do:
  *
  * {{{
- * $ware = new BlogMiddleware(['for' => '/blog']);
+ * $filter = new BlogFilter(['for' => '/blog']);
  * }}}
  *
- * When the above middleware is connected to a dispatcher it will only fire
+ * When the above filter is connected to a dispatcher it will only fire
  * its `beforeDispatch` and `afterDispatch` methods on requests that start with `/blog`.
  *
  * ### Limiting filters based on conditions
@@ -43,7 +45,7 @@ use Cake\Event\EventListener;
  * or response conditions. For example:
  *
  * {{{
- * $cookieMonster = new CookieMiddleware([
+ * $cookieMonster = new CookieFilter([
  *   'when' => function ($req, $res) {
  *     // Custom code goes here.
  *   }

src/Routing/Filter/RoutingFilter.php

@@ -1,5 +1,17 @@
 <?php
-
+/**
+ * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
+ * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * For full copyright and license information, please see the LICENSE.txt
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ * @link          http://cakephp.org CakePHP(tm) Project
+ * @since         3.0.0
+ * @license       http://www.opensource.org/licenses/mit-license.php MIT License
+ */
 namespace Cake\Routing\Filter;
 
 use Cake\Event\Event;

src/TestSuite/ControllerTestCase.php

@@ -249,7 +249,7 @@ abstract class ControllerTestCase extends TestCase {
 
 		$Dispatch = new ControllerTestDispatcher();
 		foreach (DispatcherFactory::filters() as $filter) {
-			$Dispatch->add($filter);
+			$Dispatch->addFilter($filter);
 		}
 		if ($this->_dirtyController) {
 			$this->controller = null;

tests/TestCase/Routing/DispatcherFactoryTest.php

@@ -33,7 +33,7 @@ class DispatcherFactoryTest extends TestCase {
 	}
 
 /**
- * Test add middleware
+ * Test add filter
  *
  * @return void
  */
@@ -44,7 +44,7 @@ class DispatcherFactoryTest extends TestCase {
 	}
 
 /**
- * Test add middleware as a string
+ * Test add filter as a string
  *
  * @return void
  */
@@ -54,7 +54,7 @@ class DispatcherFactoryTest extends TestCase {
 	}
 
 /**
- * Test add middleware missing
+ * Test add filter missing
  *
  * @expectedException Cake\Routing\Error\MissingDispatcherFilterException
  * @return void
@@ -73,7 +73,7 @@ class DispatcherFactoryTest extends TestCase {
 		DispatcherFactory::add($mw);
 		$result = DispatcherFactory::create();
 		$this->assertInstanceOf('Cake\Routing\Dispatcher', $result);
-		$this->assertCount(1, $result->middleware());
+		$this->assertCount(1, $result->filters());
 	}
 
 }

tests/TestCase/Routing/DispatcherTest.php

@@ -463,7 +463,7 @@ class DispatcherTest extends TestCase {
 			->method('beforeDispatch');
 		$filter->expects($this->at(1))
 			->method('afterDispatch');
-		$dispatcher->add($filter);
+		$dispatcher->addFilter($filter);
 
 		$request = new Request([
 			'url' => '/',
@@ -501,7 +501,7 @@ class DispatcherTest extends TestCase {
 		$request = new Request();
 		$res = new Response();
 		$dispatcher = new Dispatcher();
-		$dispatcher->add($filter);
+		$dispatcher->addFilter($filter);
 		$dispatcher->dispatch($request, $res);
 	}
 
@@ -533,7 +533,7 @@ class DispatcherTest extends TestCase {
 			]
 		]);
 		$dispatcher = new Dispatcher();
-		$dispatcher->add($filter);
+		$dispatcher->addFilter($filter);
 		$dispatcher->dispatch($request, $response);
 	}
 

tests/TestCase/Routing/Filter/AssetFilterTest.php

@@ -22,6 +22,9 @@ use Cake\Network\Response;
 use Cake\Routing\Filter\AssetFilter;
 use Cake\TestSuite\TestCase;
 
+/**
+ * Asset filter test case.
+ */
 class AssetFilterTest extends TestCase {
 
 /**

tests/TestCase/Routing/Filter/CacheFilterTest.php

@@ -88,7 +88,7 @@ class CacheFilterTest extends TestCase {
 		Router::connect('/:controller/:action/*');
 
 		$dispatcher = new Dispatcher();
-		$dispatcher->add(new RoutingFilter());
+		$dispatcher->addFilter(new RoutingFilter());
 		$request = new Request($url);
 		$response = $this->getMock('Cake\Network\Response', array('send'));
 
@@ -98,8 +98,8 @@ class CacheFilterTest extends TestCase {
 		$request = new Request($url);
 		$response = $this->getMock('Cake\Network\Response', array('send'));
 		$dispatcher = new Dispatcher();
-		$dispatcher->add(new RoutingFilter());
-		$dispatcher->add(new CacheFilter());
+		$dispatcher->addFilter(new RoutingFilter());
+		$dispatcher->addFilter(new CacheFilter());
 		$dispatcher->dispatch($request, $response);
 		$cached = $response->body();