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\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 @@ protected function _loadController($request) {
 		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 @@ protected static function _createFilter($name) {
 	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,17 +24,19 @@
  * 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.
  * Both the before and after event will have the same conditions applied to them. For
  * 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 @@
  * 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 @@ protected function _testAction($url = '', $options = array()) {
 
 		$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 @@ public function setUp() {
 	}
 
 /**
- * Test add middleware
+ * Test add filter
  *
  * @return void
  */
@@ -44,7 +44,7 @@ public function testAddFilter() {
 	}
 
 /**
- * Test add middleware as a string
+ * Test add filter as a string
  *
  * @return void
  */
@@ -54,7 +54,7 @@ public function testAddFilterString() {
 	}
 
 /**
- * Test add middleware missing
+ * Test add filter missing
  *
  * @expectedException Cake\Routing\Error\MissingDispatcherFilterException
  * @return void
@@ -73,7 +73,7 @@ public function testCreate() {
 		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 @@ public function testDispatcherFilter() {
 			->method('beforeDispatch');
 		$filter->expects($this->at(1))
 			->method('afterDispatch');
-		$dispatcher->add($filter);
+		$dispatcher->addFilter($filter);
 
 		$request = new Request([
 			'url' => '/',
@@ -501,7 +501,7 @@ public function testBeforeDispatchAbortDispatch() {
 		$request = new Request();
 		$res = new Response();
 		$dispatcher = new Dispatcher();
-		$dispatcher->add($filter);
+		$dispatcher->addFilter($filter);
 		$dispatcher->dispatch($request, $res);
 	}
 
@@ -533,7 +533,7 @@ public function testAfterDispatchReplaceResponse() {
 			]
 		]);
 		$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\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 @@ public function testFullPageCachingDispatch($url) {
 		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 @@ public function testFullPageCachingDispatch($url) {
 		$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();