Various documentation and whitespace fixes.

core/includes/common.inc

@@ -1,10 +1,10 @@
 <?php
 
-use Drupal\Component\Utility\NestedArray;
+use Symfony\Component\DependencyInjection\Container;
 use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Drupal\Component\Utility\NestedArray;
 use Drupal\Core\Cache\CacheBackendInterface;
-use Symfony\Component\DependencyInjection\Container;
 use Drupal\Core\Database\Database;
 use Drupal\Core\Template\Attribute;
 

core/lib/Drupal/Core/EventSubscriber/RouteProcessorSubscriber.php

@@ -24,6 +24,9 @@ class RouteProcessorSubscriber implements EventSubscriberInterface {
 
   /**
    * Sets a default controller for a route if one was not specified.
+   *
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
+   *   Event that is created to create a response for a request.
    */
   public function onRequestSetController(GetResponseEvent $event) {
     $request = $event->getRequest();

core/lib/Drupal/Core/HtmlPageController.php

@@ -41,6 +41,7 @@ class HtmlPageController implements ContainerAwareInterface {
    *   The request object.
    * @param type $_content
    *   The body content callable that contains the body region of this page.
+   *
    * @return \Symfony\Component\HttpFoundation\Response
    */
   public function content(Request $request, $_content) {

core/lib/Drupal/Core/Routing/ChainMatcher.php

@@ -27,6 +27,7 @@ class ChainMatcher implements RequestMatcherInterface, RequestContextAwareInterf
 
   /**
    * Array of RequestMatcherInterface objects, sorted.
+   *
    * @var type
    */
   protected $sortedMatchers = array();
@@ -111,8 +112,8 @@ class ChainMatcher implements RequestMatcherInterface, RequestContextAwareInterf
     * @param MatcherInterface $matcher
     *   The matcher to add.
     * @param int $priority
-    *   The priority of the matcher. Higher number matchers will be checked
-    *   first.
+    *   (optional) The priority of the matcher. Higher number matchers will be checked
+    *   first. Default to 0.
     */
   public function add(RequestMatcherInterface $matcher, $priority = 0) {
     if (empty($this->matchers[$priority])) {

core/lib/Drupal/Core/Routing/CompiledRoute.php

@@ -36,17 +36,22 @@ class CompiledRoute {
    * @var Symfony\Component\Routing\Route
    */
   protected $route;
-
   protected $variables;
   protected $tokens;
   protected $staticPrefix;
+
+  /**
+   * The regular expression to match placeholders out of this path.
+   *
+   * @var string
+   */
   protected $regex;
 
 
   /**
    * Constructs a new CompiledRoute object.
    *
-   * @param Route  $route
+   * @param Route $route
    *   A original Route instance.
    * @param int $fit
    *   The fitness of the route.
@@ -66,7 +71,7 @@ class CompiledRoute {
   }
 
   /**
-   * Returns the fit of this route
+   * Returns the fit of this route.
    *
    * See RouteCompiler for a definition of how the fit is calculated.
    *
@@ -117,7 +122,7 @@ class CompiledRoute {
     * Returns the Route instance.
     *
     * @return Route
-    *   A Route instance
+    *   A Route instance.
     */
   public function getRoute() {
     return $this->route;
@@ -126,7 +131,8 @@ class CompiledRoute {
   /**
     * Returns the pattern.
     *
-    * @return string The pattern
+    * @return string
+    *   The pattern.
     */
   public function getPattern() {
     return $this->route->getPattern();
@@ -135,7 +141,8 @@ class CompiledRoute {
   /**
     * Returns the options.
     *
-    * @return array The options
+    * @return array
+    *   The options.
     */
   public function getOptions() {
     return $this->route->getOptions();
@@ -144,7 +151,8 @@ class CompiledRoute {
   /**
     * Returns the defaults.
     *
-    * @return array The defaults
+    * @return array
+    *   The defaults.
     */
   public function getDefaults() {
     return $this->route->getDefaults();
@@ -153,11 +161,11 @@ class CompiledRoute {
   /**
     * Returns the requirements.
     *
-    * @return array The requirements
+    * @return array
+    *   The requirements.
     */
   public function getRequirements() {
     return $this->route->getRequirements();
   }
 
 }
-

core/lib/Drupal/Core/Routing/FinalMatcherInterface.php

@@ -28,7 +28,7 @@ interface FinalMatcherInterface {
    *   A Request object against which to match.
    *
    * @return array
-   *   An array of parameters
+   *   An array of parameters.
    */
   public function matchRequest(Request $request);
 }

core/lib/Drupal/Core/Routing/FirstEntryFinalMatcher.php

@@ -35,7 +35,9 @@ class FirstEntryFinalMatcher implements FinalMatcherInterface {
     return $this;
   }
 
-
+  /**
+   * Implements Drupal\Core\Routing\FinalMatcherInterface::matchRequest().
+   */
   public function matchRequest(Request $request) {
     // Return whatever the first route in the collection is.
     foreach ($this->routes as $name => $route) {
@@ -54,12 +56,12 @@ class FirstEntryFinalMatcher implements FinalMatcherInterface {
    * Get merged default parameters.
    *
    * @param array $params
-   *  The parameters
+   *  The parameters.
    * @param array $defaults
-   *   The defaults
+   *   The defaults.
    *
    * @return array
-   *   Merged default parameters
+   *   Merged default parameters.
    */
   protected function mergeDefaults($params, $defaults) {
     $parameters = $defaults;
@@ -73,4 +75,3 @@ class FirstEntryFinalMatcher implements FinalMatcherInterface {
   }
 
 }
-

core/lib/Drupal/Core/Routing/MatcherDumper.php

@@ -39,6 +39,15 @@ class MatcherDumper implements MatcherDumperInterface {
    */
   protected $tableName;
 
+  /**
+   * Construct the MatcherDumper.
+   *
+   * @param Drupal\Core\Database\Connection $connection
+   *   The database connection which will be used to store the route
+   *   information.
+   * @param string $table
+   *   (optional) The table to store the route info in. Defaults to 'router'.
+   */
   public function __construct(Connection $connection, $table = 'router') {
     $this->connection = $connection;
 
@@ -63,21 +72,18 @@ class MatcherDumper implements MatcherDumperInterface {
    * Dumps a set of routes to the router table in the database.
    *
    * Available options:
+   * - route_set:  The route grouping that is being dumped. All existing
+   *   routes with this route set will be deleted on dump.
+   * - base_class: The base class name
    *
-   *  * route_set:  The route grouping that is being dumped. All existing
-   *     routes with this route set will be deleted on dump.
-   *  * base_class: The base class name
-   *
-   * @param $options array
-   *   $options An array of options
+   * @param array $options
+   *   An array of options
    */
   public function dump(array $options = array()) {
     $options += array(
       'route_set' => '',
     );
 
-    //$compiled = $this->compileRoutes($this->routes, $route_set);
-
     // Convert all of the routes into database records.
     $insert = $this->connection->insert($this->tableName)->fields(array(
       'name',
@@ -104,7 +110,7 @@ class MatcherDumper implements MatcherDumperInterface {
         // compiled route object. Remove this once
         // https://github.com/symfony/symfony/pull/4755 is merged and brought
         // back downstream.
-       'route' => serialize(clone($route)),
+        'route' => serialize(clone($route)),
       );
       $insert->values($values);
     }
@@ -160,4 +166,3 @@ class MatcherDumper implements MatcherDumperInterface {
     return $fit;
   }
 }
-

core/lib/Drupal/Core/Routing/NestedMatcher.php

@@ -16,9 +16,9 @@ use Symfony\Component\HttpFoundation\Request;
 class NestedMatcher implements NestedMatcherInterface {
 
   /**
-   * The final matcher
+   * The final matcher.
    *
-   * @var RequestMatcherInterface
+   * @var Symfony\Component\Routing\Matcher\RequestMatcherInterface
    */
   protected $finalMatcher;
 
@@ -32,14 +32,14 @@ class NestedMatcher implements NestedMatcherInterface {
   /**
    * The initial matcher to match against.
    *
-   * @var InitialMatcherInterface
+   * @var Drupal\core\Routing\InitialMatcherInterface
    */
   protected $initialMatcher;
 
   /**
    * The request context.
    *
-   * @var RequestContext
+   * @var Symfony\Component\Routing\RequestContext
    */
   protected $context;
 
@@ -50,7 +50,7 @@ class NestedMatcher implements NestedMatcherInterface {
    * Partial matchers will be run in the order in which they are added.
    *
    * @param PartialMatcherInterface $matcher
-   *   A partial
+   *   A partial.
    *
    * @return NestedMatcherInterface
    *   The current matcher.
@@ -101,9 +101,11 @@ class NestedMatcher implements NestedMatcherInterface {
     * If the matcher can not find information, it must throw one of the exceptions documented
     * below.
     *
-    * @param Request $request The request to match
+    * @param Request $request
+    *   The request to match.
     *
-    * @return array An array of parameters
+    * @return array
+    *   An array of parameters.
     *
     * @throws ResourceNotFoundException If no matching resource could be found
     * @throws MethodNotAllowedException If a matching resource was found but the request method is not allowed
@@ -146,4 +148,3 @@ class NestedMatcher implements NestedMatcherInterface {
   }
 
 }
-

core/lib/Drupal/Core/Routing/PathMatcher.php

@@ -17,6 +17,7 @@ use Drupal\Core\Database\Connection;
  * Initial matcher to match a route against a built database, by path.
  */
 class PathMatcher implements InitialMatcherInterface {
+
   /**
    * The database connection from which to read route information.
    *
@@ -86,6 +87,7 @@ class PathMatcher implements InitialMatcherInterface {
    *
    * @param array $parts
    *   The parts of the path for which we want candidates.
+   *
    * @return array
    *   An array of outlines that could match the specified path parts.
    */
@@ -130,4 +132,3 @@ class PathMatcher implements InitialMatcherInterface {
     return $ancestors;
   }
 }
-

core/lib/Drupal/Core/Routing/RouteBuilder.php

@@ -16,10 +16,19 @@ class RouteBuilder {
 
   protected $dumper;
 
+  /**
+   * Construcs the RouteBuilder using the passed MatcherDumperInterface
+   *
+   * @param Symfony\Component\Routing\Matcher\Dumper\MatcherDumperInterface $dumper
+   *   The matcher dumper used to store the route information.
+   */
   public function __construct(MatcherDumperInterface $dumper) {
     $this->dumper = $dumper;
   }
 
+  /**
+   * Rebuilds the route info and dumps to dumper.
+   */
   public function rebuild() {
     // We need to manually call each module so that we can know which module
     // a given item came from.

core/lib/Drupal/Core/Routing/RouteCompiler.php

@@ -22,18 +22,18 @@ class RouteCompiler implements RouteCompilerInterface {
 
   /**
    * Utility constant to use for regular expressions against the path.
-*/
+   */
   const REGEX_DELIMITER = '#';
 
   /**
-    * Compiles the current route instance.
-    *
-    * @param \Symfony\Component\Routing\Route $route
-    *   A Route instance
-    *
-    * @return CompiledRoute
-    *   A CompiledRoute instance
-    */
+   * Compiles the current route instance.
+   *
+   * @param \Symfony\Component\Routing\Route $route
+   *   A Route instance.
+   *
+   * @return CompiledRoute
+   *   A CompiledRoute instance.
+   */
   public function compile(Route $route) {
 
     $stripped_path = $this->getPathWithoutDefaults($route);
@@ -62,7 +62,9 @@ class RouteCompiler implements RouteCompilerInterface {
    *   The route object.
    * @param string $pattern
    *   The pattern for which we want a matching regex.
+   *
    * @return type
+   *
    * @throws \LogicException
    */
   public function getRegex(Route $route, $pattern) {
@@ -107,11 +109,11 @@ class RouteCompiler implements RouteCompilerInterface {
     }
 
     // find the first optional token
-    $firstOptional = INF;
+    $first_optional = INF;
     for ($i = count($tokens) - 1; $i >= 0; $i--) {
         $token = $tokens[$i];
         if ('variable' === $token[0] && $route->hasDefault($token[3])) {
-            $firstOptional = $i;
+            $first_optional = $i;
         } else {
             break;
         }
@@ -120,50 +122,56 @@ class RouteCompiler implements RouteCompilerInterface {
     // compute the matching regexp
     $regexp = '';
     for ($i = 0, $nbToken = count($tokens); $i < $nbToken; $i++) {
-        $regexp .= $this->computeRegexp($tokens, $i, $firstOptional);
+        $regexp .= $this->computeRegexp($tokens, $i, $first_optional);
     }
 
     return self::REGEX_DELIMITER.'^'.$regexp.'$'.self::REGEX_DELIMITER.'s';
   }
 
   /**
-    * Computes the regexp used to match a specific token. It can be static text or a subpattern.
-    *
-    * @param array   $tokens        The route tokens
-    * @param integer $index         The index of the current token
-    * @param integer $firstOptional The index of the first optional token
-    *
-    * @return string The regexp pattern for a single token
-    */
-  private function computeRegexp(array $tokens, $index, $firstOptional) {
-      $token = $tokens[$index];
-      if ('text' === $token[0]) {
-          // Text tokens
-          return preg_quote($token[1], self::REGEX_DELIMITER);
-      } else {
-          // Variable tokens
-          if (0 === $index && 0 === $firstOptional) {
-              // When the only token is an optional variable token, the separator is required
-              return sprintf('%s(?<%s>%s)?', preg_quote($token[1], self::REGEX_DELIMITER), $token[3], $token[2]);
-          } else {
-              $regexp = sprintf('%s(?<%s>%s)', preg_quote($token[1], self::REGEX_DELIMITER), $token[3], $token[2]);
-              if ($index >= $firstOptional) {
-                  // Enclose each optional token in a subpattern to make it optional.
-                  // "?:" means it is non-capturing, i.e. the portion of the subject string that
-                  // matched the optional subpattern is not passed back.
-                  $regexp = "(?:$regexp";
-                  $nbTokens = count($tokens);
-                  if ($nbTokens - 1 == $index) {
-                      // Close the optional subpatterns
-                      $regexp .= str_repeat(")?", $nbTokens - $firstOptional - (0 === $firstOptional ? 1 : 0));
-                  }
-              }
-
-              return $regexp;
-          }
+   * Computes the regexp used to match a specific token. It can be static text or a subpattern.
+   *
+   * @param array $tokens
+   *   The route tokens
+   * @param integer $index
+   *   The index of the current token
+   * @param integer $first_optional
+   *   The index of the first optional token
+   *
+   * @return string
+   *   The regexp pattern for a single token
+   */
+  private function computeRegexp(array $tokens, $index, $first_optional) {
+    $token = $tokens[$index];
+    if ('text' === $token[0]) {
+      // Text tokens
+      return preg_quote($token[1], self::REGEX_DELIMITER);
+    }
+    else {
+      // Variable tokens
+      if (0 === $index && 0 === $first_optional) {
+        // When the only token is an optional variable token, the separator is
+        // required.
+        return sprintf('%s(?<%s>%s)?', preg_quote($token[1], self::REGEX_DELIMITER), $token[3], $token[2]);
       }
-  }
+      else {
+        $regexp = sprintf('%s(?<%s>%s)', preg_quote($token[1], self::REGEX_DELIMITER), $token[3], $token[2]);
+        if ($index >= $first_optional) {
+          // Enclose each optional token in a subpattern to make it optional.
+          // "?:" means it is non-capturing, i.e. the portion of the subject
+          // string that matched the optional subpattern is not passed back.
+          $regexp = "(?:$regexp";
+          $nbTokens = count($tokens);
+          if ($nbTokens - 1 == $index) {
+            // Close the optional subpatterns.
+            $regexp .= str_repeat(")?", $nbTokens - $first_optional - (0 === $first_optional ? 1 : 0));
+          }
+        }
 
+        return $regexp;
+      }
+    }
+  }
 
   /**
    * Returns the pattern outline.
@@ -217,6 +225,7 @@ class RouteCompiler implements RouteCompilerInterface {
    * problem.
    *
    * @param \Symfony\Component\Routing\Route $route
+   *   The route to have the placeholders removed from.
    *
    * @return string
    *   The path string, stripped of placeholders that have default values.
@@ -236,4 +245,3 @@ class RouteCompiler implements RouteCompilerInterface {
   }
 
 }
-

core/modules/system/lib/Drupal/system/Tests/Routing/ChainMatcherTest.php

@@ -22,6 +22,7 @@ use Exception;
  * Basic tests for the ChainMatcher.
  */
 class ChainMatcherTest extends UnitTestBase {
+  
   public static function getInfo() {
     return array(
       'name' => 'Chain matcher tests',

core/modules/system/lib/Drupal/system/Tests/Routing/FirstEntryFinalMatcherTest.php

@@ -44,9 +44,6 @@ class FirstEntryFinalMatcherTest extends UnitTestBase {
 
     $this->fixtures = new RoutingFixtures();
   }
-  public function setUp() {
-    parent::setUp();
-  }
 
   /**
    * Confirms the final matcher returns correct attributes for static paths.
@@ -113,4 +110,3 @@ class FirstEntryFinalMatcherTest extends UnitTestBase {
     $this->assertEqual($attributes['value'], 'poink', 'Optional placeholder value used default.');
   }
 }
-

core/modules/system/lib/Drupal/system/Tests/Routing/HttpMethodMatcherTest.php

@@ -44,10 +44,7 @@ class HttpMethodMatcherTest extends UnitTestBase {
 
     $this->fixtures = new RoutingFixtures();
   }
-  public function setUp() {
-    parent::setUp();
-  }
-
+  
   /**
    * Confirms that the HttpMethod matcher matches properly.
    */
@@ -106,4 +103,3 @@ class HttpMethodMatcherTest extends UnitTestBase {
 
   }
 }
-

core/modules/system/lib/Drupal/system/Tests/Routing/MockMatcher.php

@@ -21,6 +21,9 @@ use Closure;
  */
 class MockMatcher implements RequestMatcherInterface {
 
+  /**
+   * The matcher being tested.
+   */
   protected $matcher;
 
   public function __construct(Closure $matcher) {
@@ -32,4 +35,3 @@ class MockMatcher implements RequestMatcherInterface {
     return $matcher($request);
   }
 }
-

core/modules/system/lib/Drupal/system/Tests/Routing/MockPathMatcher.php

@@ -9,14 +9,23 @@ use Symfony\Component\Routing\RouteCollection;
 use Drupal\Core\Routing\InitialMatcherInterface;
 
 /**
- * Description of MockPathMatcher
- *
- * @author crell
+ * Provides a mock path matcher.
  */
 class MockPathMatcher implements InitialMatcherInterface {
 
+  /**
+   * Routes to be matched.
+   *
+   * @var Symfony\Component\Routing\RouteCollection
+   */
   protected $routes;
 
+  /**
+   * Construct the matcher given the route collection.
+   *
+   * @param Symfony\Component\Routing\RouteCollection $routes
+   *   The routes being matched.
+   */
   public function __construct(RouteCollection $routes) {
     $this->routes = $routes;
   }

core/modules/system/lib/Drupal/system/Tests/Routing/NestedMatcherTest.php

@@ -44,9 +44,6 @@ class NestedMatcherTest extends UnitTestBase {
 
     $this->fixtures = new RoutingFixtures();
   }
-  public function setUp() {
-    parent::setUp();
-  }
 
   /**
    * Confirms we can nest multiple partial matchers.
@@ -66,4 +63,3 @@ class NestedMatcherTest extends UnitTestBase {
     $this->assertEqual($attributes['_route'], 'route_a', 'The correct matching route was found.');
   }
 }
-

core/modules/system/lib/Drupal/system/Tests/Routing/PathMatcherTest.php

@@ -48,7 +48,7 @@ class PathMatcherTest extends UnitTestBase {
   public function tearDown() {
     $this->fixtures->dropTables(Database::getConnection());
 
-   parent::tearDown();
+    parent::tearDown();
   }
 
   /**
@@ -63,8 +63,6 @@ class PathMatcherTest extends UnitTestBase {
 
     $candidates = $matcher->getCandidateOutlines($parts);
 
-    //debug($candidates);
-
     $candidates = array_flip($candidates);
 
     $this->assertTrue(count($candidates) == 4, 'Correct number of candidates found');
@@ -275,7 +273,7 @@ class PathMatcherTest extends UnitTestBase {
   }
 
   /**
-   * Confirm that an exception is thrown when no matching path is found.
+   * Confirms that an exception is thrown when no matching path is found.
    */
   function testOutlinePathNoMatch() {
     $connection = Database::getConnection();

core/modules/system/lib/Drupal/system/Tests/Routing/RouteTest.php

@@ -45,8 +45,8 @@ class RouteTest extends UnitTestBase {
    * Confirms that a compiled route with default values has the correct outline.
    */
   public function testCompilationDefaultValue() {
-    // Because "here" has a default value, it should not factor into the
-    // outline or the fitness.
+    // Because "here" has a default value, it should not factor into the outline
+    // or the fitness.
     $route = new Route('/test/{something}/more/{here}', array(
       'here' => 'there',
     ));

core/modules/system/lib/Drupal/system/Tests/Routing/RoutingFixtures.php

@@ -12,6 +12,12 @@ use Drupal\Core\Database\Connection;
  */
 class RoutingFixtures {
 
+  /**
+   * Create the tables required for the sample data.
+   *
+   * @param Drupal\Core\Database\Connection $connection
+   *   The connection to use to create the tables.
+   */
   public function createTables(Connection $connection) {
     $tables = $this->routingTableDefinition();
     $schema = $connection->schema();
@@ -22,6 +28,12 @@ class RoutingFixtures {
     }
   }
 
+  /**
+   * Drop the tables used for the sample data.
+   *
+   * @param Drupal\Core\Database\Connection $connection
+   *   The connection to use to drop the tables.
+   */
   public function dropTables(Connection $connection) {
     $tables = $this->routingTableDefinition();
     $schema = $connection->schema();
@@ -91,6 +103,12 @@ class RoutingFixtures {
     return $collection;
   }
 
+  /**
+   * Returns the table definition for the routing fixtures.
+   *
+   * @return array
+   *   Table definitions.
+   */
   public function routingTableDefinition() {
 
     $tables['test_routes'] = array(