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.
    */