Various and sundry documentation formatting fixes.

core/lib/Drupal/Core/HtmlPageController.php

@@ -20,14 +20,14 @@ class HtmlPageController implements ContainerAwareInterface {
   /**
    * The injection container for this object.
    *
-   * @var ContainerInterface
+   * @var \Symfony\Component\DependencyInjection\ContainerInterface
    */
   protected $container;
 
   /**
    * Injects the service container used by this object.
    *
-   * @param ContainerInterface $container
+   * @param \Symfony\Component\DependencyInjection\ContainerInterface $container
    *   The service container this object should use.
    */
   public function setContainer(ContainerInterface $container = NULL) {
@@ -39,10 +39,11 @@ class HtmlPageController implements ContainerAwareInterface {
    *
    * @param Request $request
    *   The request object.
-   * @param type $_content
+   * @param callable $_content
    *   The body content callable that contains the body region of this page.
    *
    * @return \Symfony\Component\HttpFoundation\Response
+   *   A response object.
    */
   public function content(Request $request, $_content) {
 
@@ -53,8 +54,12 @@ class HtmlPageController implements ContainerAwareInterface {
     // https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/InternalController.php
     $attributes = $request->attributes;
     $controller = $_content;
+
+    // We need to clean off the derived information and such so that the
+    // subrequest can be processed properly without leaking data through.
     $attributes->remove('system_path');
     $attributes->remove('_content');
+
     $response = $this->container->get('http_kernel')->forward($controller, $attributes->all(), $request->query->all());
 
     $page_content = $response->getContent();

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\ChainMatcher.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -59,8 +64,6 @@ class ChainMatcher implements RequestMatcherInterface, RequestContextAwareInterf
    *
    * @param Symfony\Component\Routing\RequestContext $context
    *   The context.
-   *
-   * @api
    */
   public function setContext(RequestContext $context) {
     $this->context = $context;
@@ -87,8 +90,10 @@ class ChainMatcher implements RequestMatcherInterface, RequestContextAwareInterf
    *
    * @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
+   * @throws \Symfony\Component\Routing\Exception\ResourceNotFoundException
+   *   If no matching resource could be found
+   * @throws \Symfony\Component\Routing\Exception\MethodNotAllowedException
+   *   If a matching resource was found but the request method is not allowed
    */
   public function matchRequest(Request $request) {
     $methodNotAllowed = null;

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\CompiledRoute.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\Routing\Route;
@@ -36,9 +41,6 @@ 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.
@@ -47,19 +49,18 @@ class CompiledRoute {
    */
   protected $regex;
 
-
   /**
    * Constructs a new CompiledRoute object.
    *
-   * @param Route $route
+   * @param \Symfony\Component\Routing\Route $route
    *   A original Route instance.
    * @param int $fit
    *   The fitness of the route.
    * @param string $fit
    *   The pattern outline for this route.
-   *  @param int $num_parts
+   * @param int $num_parts
    *   The number of parts in the path.
-   *  @param string $regex
+   * @param string $regex
    *   The regular expression to match placeholders out of this path.
    */
   public function __construct(Route $route, $fit, $pattern_outline, $num_parts, $regex) {
@@ -119,51 +120,51 @@ class CompiledRoute {
   }
 
   /**
-    * Returns the Route instance.
-    *
-    * @return Route
-    *   A Route instance.
-    */
+   * Returns the Route instance.
+   *
+   * @return Route
+   *   A Route instance.
+   */
   public function getRoute() {
     return $this->route;
   }
 
   /**
-    * Returns the pattern.
-    *
-    * @return string
-    *   The pattern.
-    */
+   * Returns the pattern.
+   *
+   * @return string
+   *   The pattern.
+   */
   public function getPattern() {
     return $this->route->getPattern();
   }
 
   /**
-    * Returns the options.
-    *
-    * @return array
-    *   The options.
-    */
+   * Returns the options.
+   *
+   * @return array
+   *   The options.
+   */
   public function getOptions() {
     return $this->route->getOptions();
   }
 
   /**
-    * Returns the defaults.
-    *
-    * @return array
-    *   The defaults.
-    */
+   * Returns the defaults.
+   *
+   * @return array
+   *   The defaults.
+   */
   public function getDefaults() {
     return $this->route->getDefaults();
   }
 
   /**
-    * Returns the requirements.
-    *
-    * @return array
-    *   The requirements.
-    */
+   * Returns the requirements.
+   *
+   * @return array
+   *   The requirements.
+   */
   public function getRequirements() {
     return $this->route->getRequirements();
   }

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\FinalMatcherInterface.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -13,10 +18,10 @@ interface FinalMatcherInterface {
   /**
    * Sets the route collection this matcher should use.
    *
-   * @param RouteCollection $collection
+   * @param \Symfony\Component\Routing\RouteCollection $collection
    *   The collection against which to match.
    *
-   * @return FinalMatcherInterface
+   * @return \Drupal\Core\Routing\FinalMatcherInterface
    *   The current matcher.
    */
   public function setCollection(RouteCollection $collection);
@@ -24,7 +29,7 @@ interface FinalMatcherInterface {
   /**
    * Matches a request against multiple routes.
    *
-   * @param Request $request
+   * @param \Symfony\Component\HttpFoundation\Request $request
    *   A Request object against which to match.
    *
    * @return array

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\FirstEntryFinalMatcher.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -23,10 +28,10 @@ class FirstEntryFinalMatcher implements FinalMatcherInterface {
   /**
    * Sets the route collection this matcher should use.
    *
-   * @param RouteCollection $collection
+   * @param \Symfony\Component\Routing\RouteCollection $collection
    *   The collection against which to match.
    *
-   * @return FinalMatcherInterface
+   * @return \Drupal\Core\Routing\FinalMatcherInterface
    *   The current matcher.
    */
   public function setCollection(RouteCollection $collection) {

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\HttpMethodMatcher.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -14,10 +19,10 @@ class HttpMethodMatcher extends PartialMatcher {
   /**
    * Matches a request against multiple routes.
    *
-   * @param Request $request
+   * @param \Symfony\Component\HttpFoundation\Request $request
    *   A Request object against which to match.
    *
-   * @return RouteCollection
+   * @return \Symfony\Component\Routing\RouteCollection
    *   A RouteCollection of matched routes.
    */
   public function matchRequestPartial(Request $request) {

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\InitialMatcherInterface.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -12,10 +17,10 @@ interface InitialMatcherInterface {
   /**
    * Matches a request against multiple routes.
    *
-   * @param Request $request
+   * @param \Symfony\Component\HttpFoundation\Request $request
    *   A Request object against which to match.
    *
-   * @return RouteCollection
+   * @return \Symfony\Component\Routing\RouteCollection
    *   A RouteCollection of matched routes.
    */
   public function matchRequestPartial(Request $request);

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\MatcherDumper.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\Routing\Matcher\Dumper\MatcherDumperInterface;
@@ -57,7 +62,8 @@ class MatcherDumper implements MatcherDumperInterface {
   /**
    * Adds additional routes to be dumped.
    *
-   * @param RouteCollection $routes
+   * @param Symfony\Component\Routing\RouteCollection $routes
+   *   A collection of routes to add to this dumper.
    */
   public function addRoutes(RouteCollection $routes) {
     if (empty($this->routes)) {
@@ -74,10 +80,10 @@ class MatcherDumper implements MatcherDumperInterface {
    * 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
+   * - base_class: The base class name.
    *
    * @param array $options
-   *   An array of options
+   *   An array of options.
    */
   public function dump(array $options = array()) {
     $options += array(
@@ -136,7 +142,7 @@ class MatcherDumper implements MatcherDumperInterface {
   /**
    * Gets the routes to match.
    *
-   * @return RouteCollection
+   * @return \Symfony\Component\Routing\RouteCollection
    *   A RouteCollection instance representing all routes currently in the
    *   dumper.
    */

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

@@ -43,14 +43,13 @@ class NestedMatcher implements NestedMatcherInterface {
    */
   protected $context;
 
-
   /**
    * Adds a partial matcher to the matching plan.
    *
    * Partial matchers will be run in the order in which they are added.
    *
-   * @param PartialMatcherInterface $matcher
-   *   A partial.
+   * @param \Drupal\Core\Routing\PartialMatcherInterface $matcher
+   *   A partial matcher.
    *
    * @return NestedMatcherInterface
    *   The current matcher.
@@ -64,11 +63,11 @@ class NestedMatcher implements NestedMatcherInterface {
   /**
    * Sets the final matcher for the matching plan.
    *
-   * @param UrlMatcherInterface $final
+   * @param \Drupal\Core\Routing\FinalMatcherInterface $final
    *   The matcher that will be called last to ensure only a single route is
    *   found.
    *
-   * @return NestedMatcherInterface
+   * @return \Drupal\Core\Routing\NestedMatcherInterface
    *   The current matcher.
    */
   public function setFinalMatcher(FinalMatcherInterface $final) {
@@ -82,11 +81,11 @@ class NestedMatcher implements NestedMatcherInterface {
    *
    * Partial matchers will be run in the order in which they are added.
    *
-   * @param InitialMatcherInterface $matcher
+   * @param \Drupal\Core\Routing\InitialMatcherInterface $matcher
    *   An initial matcher.  It is responsible for its own configuration and
    *   initial route collection
    *
-   * @return NestedMatcherInterface
+   * @return \Drupal\Core\Routing\NestedMatcherInterface
    *   The current matcher.
    */
   public function setInitialMatcher(InitialMatcherInterface $initial) {
@@ -96,20 +95,22 @@ class NestedMatcher implements NestedMatcherInterface {
   }
 
   /**
-    * Tries to match a request with a set of routes.
-    *
-    * If the matcher can not find information, it must throw one of the exceptions documented
-    * below.
-    *
-    * @param Request $request
-    *   The request to match.
-    *
-    * @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
-    */
+   * Tries to match a request with a set of routes.
+   *
+   * If the matcher can not find information, it must throw one of the
+   * exceptions documented below.
+   *
+   * @param \Symfony\Component\HttpFoundation\Request $request
+   *   The request to match.
+   *
+   * @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.
+   */
   public function matchRequest(Request $request) {
     $collection = $this->initialMatcher->matchRequestPartial($request);
 
@@ -130,7 +131,8 @@ class NestedMatcher implements NestedMatcherInterface {
    *
    * This method is unused. It is here only to satisfy the interface.
    *
-   * @param RequestContext $context The context
+   * @param \Symfony\Component\Routing\RequestContext $context
+   *   The context
    */
   public function setContext(RequestContext $context) {
     $this->context = $context;
@@ -141,7 +143,8 @@ class NestedMatcher implements NestedMatcherInterface {
    *
    * This method is unused. It is here only to satisfy the interface.
    *
-   * @return RequestContext The context
+   * @return \Symfony\Component\Routing\RequestContext
+   *   The context
    */
   public function getContext() {
     return $this->context;

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\NestedMatcherInterface.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\Routing\Matcher\RequestMatcherInterface;
@@ -14,11 +19,11 @@ interface NestedMatcherInterface extends RequestMatcherInterface {
    *
    * Partial matchers will be run in the order in which they are added.
    *
-   * @param InitialMatcherInterface $matcher
+   * @param \Drupal\Core\Routing\InitialMatcherInterface $matcher
    *   An initial matcher.  It is responsible for its own configuration and
    *   initial route collection
    *
-   * @return NestedMatcherInterface
+   * @return \Drupal\Core\Routing\NestedMatcherInterface
    *   The current matcher.
    */
   public function setInitialMatcher(InitialMatcherInterface $initial);
@@ -28,10 +33,10 @@ interface NestedMatcherInterface extends RequestMatcherInterface {
    *
    * Partial matchers will be run in the order in which they are added.
    *
-   * @param PartialMatcherInterface $matcher
+   * @param \Drupal\Core\Routing\PartialMatcherInterface $matcher
    *   A partial matcher.
    *
-   * @return NestedMatcherInterface
+   * @return \Drupal\Core\Routing\NestedMatcherInterface
    *   The current matcher.
    */
   public function addPartialMatcher(PartialMatcherInterface $matcher);
@@ -39,11 +44,11 @@ interface NestedMatcherInterface extends RequestMatcherInterface {
   /**
    * Sets the final matcher for the matching plan.
    *
-   * @param FinalMatcherInterface $final
+   * @param \Drupal\Core\Routing\FinalMatcherInterface $final
    *   The matcher that will be called last to ensure only a single route is
    *   found.
    *
-   * @return NestedMatcherInterface
+   * @return \Drupal\Core\Routing\NestedMatcherInterface
    *   The current matcher.
    */
   public function setFinalMatcher(FinalMatcherInterface $final);

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\PartialMatcher.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -13,17 +18,17 @@ abstract class PartialMatcher implements PartialMatcherInterface {
   /**
    * The RouteCollection this matcher should match against.
    *
-   * @var RouteCollection
+   * @var \Symfony\Component\Routing\RouteCollection
    */
   protected $routes;
 
   /**
    * Sets the route collection this matcher should use.
    *
-   * @param RouteCollection $collection
+   * @param \Symfony\Component\Routing\RouteCollection $collection
    *   The collection against which to match.
    *
-   * @return PartialMatcherInterface
+   * @return \Drupal\Core\Routing\PartialMatcherInterface
    *   The current matcher.
    */
   public function setCollection(RouteCollection $collection) {

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\PathMatcherInterface.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -13,10 +18,10 @@ interface PartialMatcherInterface {
   /**
    * Sets the route collection this matcher should use.
    *
-   * @param RouteCollection $collection
+   * @param \Symfony\Component\Routing\RouteCollection $collection
    *   The collection against which to match.
    *
-   * @return PartialMatcherInterface
+   * @return \Drupal\Core\Routing\PartialMatcherInterface
    *   The current matcher.
    */
   public function setCollection(RouteCollection $collection);
@@ -24,10 +29,10 @@ interface PartialMatcherInterface {
   /**
    * Matches a request against multiple routes.
    *
-   * @param Request $request
+   * @param \Symfony\Component\HttpFoundation\Request $request
    *   A Request object against which to match.
    *
-   * @return RouteCollection
+   * @return \Symfony\Component\Routing\RouteCollection
    *   A RouteCollection of matched routes.
    */
   public function matchRequestPartial(Request $request);

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

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\Routing\RouteBuilder.
+ */
+
 namespace Drupal\Core\Routing;
 
 use Symfony\Component\Routing\RouteCompilerInterface;
@@ -14,10 +19,15 @@ use Symfony\Component\Routing\Matcher\Dumper\MatcherDumperInterface;
  */
 class RouteBuilder {
 
+  /**
+   * The dumper to which we should send collected routes.
+   *
+   * @var \Symfony\Component\Routing\Matcher\Dumper\MatcherDumperInterface
+   */
   protected $dumper;
 
   /**
-   * Construcs the RouteBuilder using the passed MatcherDumperInterface
+   * Construcs the RouteBuilder using the passed MatcherDumperInterface.
    *
    * @param Symfony\Component\Routing\Matcher\Dumper\MatcherDumperInterface $dumper
    *   The matcher dumper used to store the route information.

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

@@ -31,7 +31,7 @@ class RouteCompiler implements RouteCompilerInterface {
    * @param \Symfony\Component\Routing\Route $route
    *   A Route instance.
    *
-   * @return CompiledRoute
+   * @return \Drupal\Core\Routing\CompiledRoute
    *   A CompiledRoute instance.
    */
   public function compile(Route $route) {
@@ -63,7 +63,8 @@ class RouteCompiler implements RouteCompilerInterface {
    * @param string $pattern
    *   The pattern for which we want a matching regex.
    *
-   * @return type
+   * @return string
+   *   A regular expression that will match a path against this route.
    *
    * @throws \LogicException
    */