Detailed cleanup of documentation blocks for spacing, language, placement, etc.

core/includes/bootstrap.inc

@@ -1537,15 +1537,17 @@ function request_uri($omit_query_string = FALSE) {
 }
 
 /**
- * Returns the current global reuqest object.
+ * Returns the current global request object.
  *
  * @todo Replace this function with a proper dependency injection container.
  *
- * @staticvar Request $request
- * @param Request $new_request
- *   The new request object to store. If you are not index.php, you probably
- *   should not be using this parameter.
- * @return Request
+ * @staticvar Symfony\Component\HttpFoundation\Request $request
+ *
+ * @param Symfony\Component\HttpFoundation\Request $new_request
+ *   Optional. The new request object to store. This parameter should only be
+ *   used by index.php.
+ *
+ * @return Symfony\Component\HttpFoundation\Request
  *   The current request object.
  */
 function request(Request $new_request = NULL) {

core/includes/install.core.inc

@@ -480,10 +480,10 @@ function install_run_task($task, &$install_state) {
       include_once DRUPAL_ROOT . '/core/includes/batch.inc';
       $output = _batch_page();
       // Because Batch API now returns a JSON response for intermediary steps,
-      // but the installer doesn't handle Response objects yet, we will just
-      // send the output here and emulate the old model.
-      // @todo: Replace this when we refactor the installer to use a
-      // Request/Response workflow.
+      // but the installer doesn't handle Response objects yet, just send the
+      // output here and emulate the old model.
+      // @todo Replace this when we refactor the installer to use a request-
+      //   response workflow.
       if ($output instanceof Response) {
         $output->send();
         $output = NULL;

core/lib/Drupal/Core/ContentNegotiation.php

@@ -13,21 +13,24 @@
  * This class is a central library for content type negotiation.
  *
  * @todo Replace this class with a real content negotiation library based on
- * mod_negotiation.  Development of that is a work in progress.
+ *   mod_negotiation. Development of that is a work in progress.
  */
 class ContentNegotiation {
 
   /**
-   * Returns the normalized type of a given request.
+   * Gets the normalized type of a request.
    *
    * The normalized type is a short, lowercase version of the format, such as
-   * "html" or "json" or "atom".
+   * 'html', 'json' or 'atom'.
    *
-   * @param Request $request
+   * @param Symfony\Component\HttpFoundation\Request $request
    *   The request object from which to extract the content type.
+   *
+   * @return
+   *   The normalized type of a given request.
    */
   public function getContentType(Request $request) {
-    // AJAX iframe uploads need special handling, because they contain a json
+    // AJAX iframe uploads need special handling, because they contain a JSON
     // response wrapped in <textarea>.
     if ($request->get('ajax_iframe_upload', FALSE)) {
       return 'iframeupload';
@@ -48,6 +51,4 @@ public function getContentType(Request $request) {
     // Do HTML last so that it always wins.
     return 'html';
   }
-
 }
-

core/lib/Drupal/Core/Database/Connection.php

@@ -524,10 +524,9 @@ public function query($query, array $args = array(), $options = array()) {
     }
     catch (PDOException $e) {
       if ($options['throw_exception']) {
-        // Wrap the exception in another exception.  Its message is the extra
-        // database debug information.  We have to do it this way because PHP
-        // does not allow us to override Exception::getMessage().
-
+        // Wrap the exception in another exception, because PHP does not allow
+        // overriding Exception::getMessage(). Its message is the extra database
+        // debug information.
         $query_string = ($query instanceof DatabaseStatementInterface) ? $stmt->getQueryString() : $query;
         $message = $e->getMessage() . ": " . $query_string . "; " . print_r($args, TRUE);
         $exception = new DatabaseExceptionWrapper($message, 0, $e);

core/lib/Drupal/Core/DrupalKernel.php

@@ -2,7 +2,6 @@
 
 /**
  * @file
- *
  * Definition of Drupal\Core\DrupalKernel.
  */
 
@@ -17,7 +16,6 @@
 use Symfony\Component\EventDispatcher\Event;
 use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
 use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
-//use Symfony\Component\HttpKernel\EventListener\RouterListener;
 use Symfony\Component\HttpKernel\EventListener\ExceptionListener;
 use Drupal\Core\EventSubscriber\ViewSubscriber;
 use Drupal\Core\EventSubscriber\AccessSubscriber;
@@ -39,25 +37,25 @@ class DrupalKernel extends HttpKernel {
     /**
      * The event dispatcher used by this kernel.
      *
-     * @var EventDispatcherInterface
+     * @var Symfony\Component\EventDispatcher\EventDispatcherInterface
      */
     protected $dispatcher;
 
     /**
      * The controller resolver that will extract the controller from a Request.
      *
-     * @var ControllerResolverInterface
+     * @var Symfony\Component\HttpKernel\Controller\ControllerResolverInterface
      */
     protected $resolver;
 
 
     /**
-     * Constructor
+     * Constructor.
      *
-     * @param EventDispatcherInterface $dispatcher
-     *   An EventDispatcherInterface instance
-     * @param ControllerResolverInterface $resolver
-     *   A ControllerResolverInterface instance
+     * @param Symfony\Component\EventDispatcher\EventDispatcherInterface $dispatcher
+     *   An EventDispatcherInterface instance.
+     * @param Symfony\Component\HttpKernel\Controller\ControllerResolverInterface $resolver
+     *   A ControllerResolverInterface instance.
      */
    public function __construct(EventDispatcherInterface $dispatcher, ControllerResolverInterface $resolver) {
       parent::__construct($dispatcher, $resolver);
@@ -71,7 +69,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso
 
       // @todo Make this extensible rather than just hard coding some.
       // @todo Add a subscriber to handle other things, too, like our Ajax
-      // replacement system.
+      //   replacement system.
       $this->dispatcher->addSubscriber(new ViewSubscriber($negotiation));
       $this->dispatcher->addSubscriber(new AccessSubscriber());
       $this->dispatcher->addSubscriber(new MaintenanceModeSubscriber());
@@ -82,7 +80,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso
       $this->dispatcher->addSubscriber(new RequestCloseSubscriber());
 
       // Some other form of error occured that wasn't handled by another kernel
-      // listener.  That could mean that it's a method/mime-type/error
+      // listener. That could mean that it's a method/mime-type/error
       // combination that is not accounted for, or some other type of error.
       // Either way, treat it as a server-level error and return an HTTP 500.
       // By default, this will be an HTML-type response because that's a decent

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

@@ -13,8 +13,7 @@
 
 /**
  * @file
- *
- * Definition of Drupal\Core\EventSubscriber\AccessSubscriber
+ * Definition of Drupal\Core\EventSubscriber\AccessSubscriber.
  */
 
 /**
@@ -26,9 +25,9 @@ class AccessSubscriber implements EventSubscriberInterface {
    * Verifies that the current user can access the requested path.
    *
    * @todo This is a total hack to keep our current access system working. It
-   * should be replaced with something robust and injected at some point.
+   *   should be replaced with something robust and injected at some point.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onKernelRequestAccessCheck(GetResponseEvent $event) {

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

@@ -19,7 +19,7 @@ class FinishResponseSubscriber implements EventSubscriberInterface {
   /**
    * Sets extra headers on successful responses.
    *
-   * @param FilterResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\FilterResponseEvent $event
    *   The event to process.
    */
   public function onRespond(FilterResponseEvent $event) {

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

 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\EventSubscriber\MaintenanceModeSubscriber.
+ */
+
 namespace Drupal\Core\EventSubscriber;
 
 use Symfony\Component\HttpFoundation\Response;
@@ -7,11 +12,6 @@
 use Symfony\Component\HttpKernel\Event\GetResponseEvent;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
-/**
- * @file
- * Definition of Drupal\Core\EventSubscriber\MaintenanceModeSubscriber.
- */
-
 /**
  * Maintenance mode subscriber for controller requests.
  */
@@ -20,7 +20,7 @@ class MaintenanceModeSubscriber implements EventSubscriberInterface {
   /**
    * Response with the maintenance page when the site is offline.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onKernelRequestMaintenanceModeCheck(GetResponseEvent $event) {

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

@@ -27,5 +27,4 @@ public function setPath(Request $request, $path) {
     // object directly.
     _current_path($path);
   }
-
 }

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

@@ -2,8 +2,7 @@
 
 /**
  * @file
- *
- * Definition of Drupal\Core\EventSubscriber\PathSubscriber
+ * Definition of Drupal\Core\EventSubscriber\PathSubscriber.
  */
 
 namespace Drupal\Core\EventSubscriber;
@@ -21,14 +20,13 @@ class PathSubscriber extends PathListenerBase implements EventSubscriberInterfac
   /**
    * Resolve the system path.
    *
-   * @todo The path system should be objectified to remove the function calls
-   * in this method.
+   * @todo The path system should be objectified to remove the function calls in
+   *   this method.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onKernelRequestPathResolve(GetResponseEvent $event) {
-
     $request = $event->getRequest();
 
     $path = $this->extractPath($request);
@@ -41,10 +39,10 @@ public function onKernelRequestPathResolve(GetResponseEvent $event) {
   /**
    * Resolve the front-page default path.
    *
-   * @todo The path system should be objectified to remove the function calls
-   * in this method.
+   * @todo The path system should be objectified to remove the function calls in
+   *   this method.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onKernelRequestFrontPageResolve(GetResponseEvent $event) {
@@ -63,10 +61,9 @@ public function onKernelRequestFrontPageResolve(GetResponseEvent $event) {
    * Decode language information embedded in the request path.
    *
    * @todo Refactor this entire method to inline the relevant portions of
-   *       drupal_language_initialize().  See the inline comment for more
-   *       details.
+   *   drupal_language_initialize(). See the inline comment for more details.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onKernelRequestLanguageResolve(GetResponseEvent $event) {
@@ -93,15 +90,15 @@ public function onKernelRequestLanguageResolve(GetResponseEvent $event) {
    *
    * Parameters in the URL sometimes represent code-meaningful strings. It is
    * therefore useful to always urldecode() those values so that individual
-   * controllers need not concern themselves with it.  This is Drupal-specific
-   * logic, and may not be familiar for developers used to other Symfony-family
+   * controllers need not concern themselves with it. This is Drupal-specific
+   * logic and may not be familiar for developers used to other Symfony-family
    * projects.
    *
    * @todo Revisit whether or not this logic is appropriate for here or if
-   *       controllers should be required to implement this logic themselves. If
-   *       we decide to keep this code, remove this TODO.
+   *   controllers should be required to implement this logic themselves. If we
+   *   decide to keep this code, remove this TODO.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onKernelRequestDecodePath(GetResponseEvent $event) {

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

 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\EventSubscriber\RequestCloseSubscriber.
+ */
+
 namespace Drupal\Core\EventSubscriber;
 
 use Symfony\Component\HttpKernel\KernelEvents;
 use Symfony\Component\HttpKernel\Event\PostResponseEvent;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
-
-/**
- * @file
- *
- * Definition of Drupal\Core\EventSubscriber\RequestCloseSubscriber;
- */
-
 /**
  * Subscriber for all responses.
  */
@@ -22,16 +20,16 @@ class RequestCloseSubscriber implements EventSubscriberInterface {
    * Performs end of request tasks.
    *
    * @todo The body of this function has just been copied almost verbatim from
-   * drupal_page_footer(), with the exception of now passing the response
-   * content to drupal_page_set_cache(). There's probably a lot in here that
-   * needs to get removed/changed.
+   *   drupal_page_footer(), with the exception of now passing the response
+   *   content to drupal_page_set_cache(). There's probably a lot in here that
+   *   needs to get removed/changed.
    *
-   * @param PostResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\PostResponseEvent $event
    *   The Event to process.
    */
   public function onTerminate(PostResponseEvent $event) {
-
     global $user;
+
     module_invoke_all('exit');
 
     // Commit the user session, if needed.

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

@@ -2,7 +2,6 @@
 
 /**
  * @file
- *
  * Definition of Drupal\Core\EventSubscriber\RouterListener;
  */
 
@@ -17,7 +16,6 @@
 use Symfony\Component\Routing\Exception\ResourceNotFoundException;
 use Symfony\Component\Routing\Exception\MethodNotFoundException;
 
-
 /**
  * Drupal-specific Router listener.
  *
@@ -40,7 +38,7 @@ public function __construct(UrlMatcherInterface $urlMatcher, LoggerInterface $lo
    * This method is nearly identical to the parent, except it passes the
    * $request->attributes->get('system_path') variable to the matcher.
    * That is where Drupal stores its processed, de-aliased, and sanitized
-   * internal path.  We also pass the full request object to the URL Matcher,
+   * internal path. We also pass the full request object to the URL Matcher,
    * since we want attributes to be available to the matcher and to controllers.
    */
   public function onKernelRequest(GetResponseEvent $event) {
@@ -80,5 +78,4 @@ public function onKernelRequest(GetResponseEvent $event) {
       throw new MethodNotAllowedHttpException($e->getAllowedMethods(), $message, $e);
     }
   }
-
 }

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

 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\EventSubscriber\ViewSubscriber.
+ */
+
 namespace Drupal\Core\EventSubscriber;
 
 use Symfony\Component\HttpFoundation\Response;
@@ -14,12 +19,6 @@
 
 use Drupal\Core\ContentNegotiation;
 
-/**
- * @file
- *
- * Definition of Drupal\Core\EventSubscriber\ViewSubscriber;
- */
-
 /**
  * Main subscriber for VIEW HTTP responses.
  */
@@ -40,7 +39,7 @@ public function __construct(ContentNegotiation $negotiation) {
    * from an JSON-type response is a JSON string, so just wrap it into a
    * Response object.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onView(GetResponseEvent $event) {
@@ -60,8 +59,6 @@ public function onView(GetResponseEvent $event) {
   public function onJson(GetResponseEvent $event) {
     $page_callback_result = $event->getControllerResult();
 
-    //print_r($page_callback_result);
-
     $response = new JsonResponse();
     $response->setContent($page_callback_result);
 
@@ -104,12 +101,12 @@ public function onIframeUpload(GetResponseEvent $event) {
    * Processes a successful controller into an HTTP 200 response.
    *
    * Some controllers may not return a response object but simply the body of
-   * one.  The VIEW event is called in that case, to allow us to mutate that
-   * body into a Response object.  In particular we assume that the return
-   * from an HTML-type response is a render array from a legacy page callback
-   * and render it.
+   * one. The VIEW event is called in that case, to allow us to mutate that
+   * body into a Response object. In particular we assume that the return from
+   * an HTML-type response is a render array from a legacy page callback and
+   * render it.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onHtml(GetResponseEvent $event) {

core/lib/Drupal/Core/ExceptionController.php

@@ -2,7 +2,6 @@
 
 /**
  * @file
- *
  * Definition of Drupal\Core\ExceptionController.
  */
 
@@ -29,24 +28,24 @@ class ExceptionController {
    *
    * We will use this to fire subrequests as needed.
    *
-   * @var HttpKernelInterface
+   * @var Symfony\Component\HttpKernel\HttpKernelInterface
    */
   protected $kernel;
 
   /**
-   * The
+   * The content negotiation library.
    *
-   * @var ContentNegotiation
+   * @var Drupal\Core\ContentNegotiation
    */
   protected $negotiation;
 
   /**
-   * Constructor
+   * Constructor.
    *
-   * @param HttpKernelInterface $kernel
+   * @param Symfony\Component\HttpKernel\HttpKernelInterface $kernel
    *   The kernel that spawned this controller, so that it can be reused
    *   for subrequests.
-   * @param ContentNegotiation $negotiation
+   * @param Drupal\Core\ContentNegotiation $negotiation
    *   The content negotiation library to use to determine the correct response
    *   format.
    */
@@ -58,15 +57,15 @@ public function __construct(HttpKernelInterface $kernel, ContentNegotiation $neg
   /**
    * Handles an exception on a request.
    *
-   * @param FlattenException $exception
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
    *   The flattened exception.
-   * @param Request $request
+   * @param Symfony\Component\HttpFoundation\Request $request
    *   The request that generated the exception.
-   * @return \Symfony\Component\HttpFoundation\Response
+   *
+   * @return Symfony\Component\HttpFoundation\Response
    *   A response object to be sent to the server.
    */
   public function execute(FlattenException $exception, Request $request) {
-
     $method = 'on' . $exception->getStatusCode() . $this->negotiation->getContentType($request);
 
     if (method_exists($this, $method)) {
@@ -74,13 +73,12 @@ public function execute(FlattenException $exception, Request $request) {
     }
 
     return new Response('A fatal error occurred: ' . $exception->getMessage(), $exception->getStatusCode());
-
   }
 
   /**
    * Processes a MethodNotAllowed exception into an HTTP 405 response.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function on405Html(FlattenException $exception, Request $request) {
@@ -90,7 +88,7 @@ public function on405Html(FlattenException $exception, Request $request) {
   /**
    * Processes an AccessDenied exception into an HTTP 403 response.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function on403Html(FlattenException $exception, Request $request) {
@@ -130,7 +128,7 @@ public function on403Html(FlattenException $exception, Request $request) {
    *
    * @param FlattenException $exception
    *   Metadata about the exception that was thrown.
-   * @param Request $request
+   * @param Symfony\Component\HttpFoundation\Request $request
    *   The request object that triggered this exception.
    */
   public function on500Html(FlattenException $exception, Request $request) {
@@ -179,24 +177,21 @@ public function on500Html(FlattenException $exception, Request $request) {
     }
 
     drupal_set_title(t('Error'));
-    // We fallback to a maintenance page at this point, because the page generation
-    // itself can generate errors.
+    // We fallback to a maintenance page at this point, because the page
+    // generation itself can generate errors.
     $output = theme('maintenance_page', array('content' => t('The website encountered an unexpected error. Please try again later.')));
 
     $response = new Response($output, 500);
     $response->setStatusCode(500, '500 Service unavailable (with message)');
 
     return $response;
-
-
-    //return _drupal_log_error(_drupal_decode_exception($exception), TRUE);
   }
 
   /**
    * This method is a temporary port of _drupal_decode_exception().
    *
-   * @todo This should get refactored.  Flatten Exception could use some
-   *       improvement as well.
+   * @todo This should get refactored. FlattenException could use some
+   *   improvement as well.
    *
    * @return array
    */
@@ -257,7 +252,6 @@ protected function decodeException(FlattenException $exception) {
    *   An associative array with keys 'file', 'line' and 'function'.
    */
   protected function getLastCaller($backtrace) {
-
     // Ignore black listed error handling functions.
     $blacklist = array('debug', '_drupal_error_handler', '_drupal_exception_handler');
 
@@ -290,7 +284,7 @@ protected function getLastCaller($backtrace) {
   /**
    * Processes a NotFound exception into an HTTP 403 response.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function on404Html(FlattenException $exception, Request $request) {
@@ -309,10 +303,10 @@ public function on404Html(FlattenException $exception, Request $request) {
 
     $path = drupal_get_normal_path(variable_get('site_404', ''));
     if ($path && $path != $system_path) {
-      // @todo: Um, how do I specify an override URL again? Totally not clear.
-      // Do that and sub-call the kernel rather than using meah().
-      // @todo: The create() method expects a slash-prefixed path, but we
-      // store a normal system path in the site_404 variable.
+      // @todo Um, how do I specify an override URL again? Totally not clear. Do
+      //   that and sub-call the kernel rather than using meah().
+      // @todo The create() method expects a slash-prefixed path, but we store a
+      //   normal system path in the site_404 variable.
       $subrequest = Request::create('/' . $path, 'get', array(), $request->cookies->all(), array(), $request->server->all());
 
       $response = $this->kernel->handle($subrequest, HttpKernelInterface::SUB_REQUEST);
@@ -337,7 +331,7 @@ public function on404Html(FlattenException $exception, Request $request) {
   /**
    * Processes an AccessDenied exception into an HTTP 403 response.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function on403Json(FlattenException $exception, Request $request) {
@@ -349,7 +343,7 @@ public function on403Json(FlattenException $exception, Request $request) {
   /**
    * Processes a NotFound exception into an HTTP 404 response.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function on404Json(FlattenException $exception, Request $request) {
@@ -361,7 +355,7 @@ public function on404Json(FlattenException $exception, Request $request) {
   /**
    * Processes a MethodNotAllowed exception into an HTTP 405 response.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function on405Json(FlattenException $exception, Request $request) {
@@ -369,5 +363,4 @@ public function on405Json(FlattenException $exception, Request $request) {
     $response->setStatusCode(405, 'Method Not Allowed');
     return $response;
   }
-
 }

core/lib/Drupal/Core/UrlMatcher.php

@@ -2,7 +2,6 @@
 
 /**
  * @file
- *
  * Definition of Drupal\Core\UrlMatcher.
  */
 
@@ -25,7 +24,7 @@ class UrlMatcher implements UrlMatcherInterface {
   /**
    * The request context for this matcher.
    *