Documentation improvements and cleanup.

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

@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\Database\DatabaseExceptionWrapper
+ * Definition of Drupal\Core\Database\DatabaseExceptionWrapper.
  */
 
 namespace Drupal\Core\Database;

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

 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\EventSubscriber\AccessSubscriber.
+ */
+
 namespace Drupal\Core\EventSubscriber;
 
 use Symfony\Component\HttpFoundation\Response;
@@ -11,11 +16,6 @@
 use Symfony\Component\Routing\Exception\MethodNotAllowedException;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
-/**
- * @file
- * Definition of Drupal\Core\EventSubscriber\AccessSubscriber.
- */
-
 /**
  * Access subscriber for controller requests.
  */

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

 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\EventSubscriber\LegacyControllerSubscriber.
+ */
+
 namespace Drupal\Core\EventSubscriber;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -7,12 +12,6 @@
 use Symfony\Component\HttpKernel\Event\FilterControllerEvent;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
-/**
- * @file
- *
- * Definition of Drupal\Core\EventSubscriber\LegacyControllerSubscriber
- */
-
 /**
  * Access subscriber for controller requests.
  */
@@ -28,20 +27,20 @@ class LegacyControllerSubscriber implements EventSubscriberInterface {
    * controller argument handling entirely and lets the old-style approach work.
    *
    * @todo Convert Drupal to use the IETF-draft-RFC style {placeholders}. That
-   * will allow us to use the native Symfony conversion, including out-of-order
-   * argument mapping, name-based mapping, and with another listener
-   * auto-conversion of parameters to full objects.  That may necessitate not
-   * using func_get_args()-based controllers.  That is likely for the best,
-   * as those are quite hard to document anyway.
+   *   will allow us to use the native Symfony conversion, including
+   *   out-of-order argument mapping, name-based mapping, and with another
+   *   listener auto-conversion of parameters to full objects. That may
+   *   necessitate not using func_get_args()-based controllers. That is likely
+   *   for the best, as those are quite hard to document anyway.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\FilterControllerEvent $event
    *   The Event to process.
    */
   public function onKernelControllerLegacy(FilterControllerEvent $event) {
     $router_item = $event->getRequest()->attributes->get('drupal_menu_item');
     $controller = $event->getController();
 
-    // This BC logic applies only to functions.  Otherwise, skip it.
+    // This BC logic applies only to functions. Otherwise, skip it.
     if (is_string($controller) && function_exists($controller)) {
       $new_controller = function() use ($router_item) {
         return call_user_func_array($router_item['page_callback'], $router_item['page_arguments']);

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

@@ -2,8 +2,7 @@
 
 /**
  * @file
- *
- * Definition of Drupal\Core\EventSubscriber\LegacyRequestSubscriber
+ * Definition of Drupal\Core\EventSubscriber\LegacyRequestSubscriber.
  */
 
 namespace Drupal\Core\EventSubscriber;
@@ -24,7 +23,7 @@ class LegacyRequestSubscriber implements EventSubscriberInterface {
   /**
    * Initializes the rest of the legacy Drupal subsystems.
    *
-   * @param GetResponseEvent $event
+   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
    *   The Event to process.
    */
   public function onKernelRequestLegacy(GetResponseEvent $event) {

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

@@ -2,8 +2,7 @@
 
 /**
  * @file
- *
- * Definition of Drupal\Core\EventSubscriber\PathListenerBase
+ * Definition of Drupal\Core\EventSubscriber\PathListenerBase.
  */
 
 namespace Drupal\Core\EventSubscriber;
@@ -24,7 +23,7 @@ public function setPath(Request $request, $path) {
     $request->attributes->set('system_path', $path);
 
     // @todo Remove this line once code has been refactored to use the request
-    // object directly.
+    //   object directly.
     _current_path($path);
   }
 }

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

@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Definition of Drupal\Core\EventSubscriber\RouterListener;
+ * Definition of Drupal\Core\EventSubscriber\RouterListener.
  */
 
 namespace Drupal\Core\EventSubscriber;
@@ -50,11 +50,11 @@ public function onKernelRequest(GetResponseEvent $event) {
     }
 
     if ($request->attributes->has('_controller')) {
-      // routing is already done
+      // Routing is already done.
       return;
     }
 
-    // add attributes based on the path info (routing)
+    // Add attributes based on the path info (routing).
     try {
       $parameters = $this->urlMatcher->match($request->attributes->get('system_path'));
 

core/lib/Drupal/Core/ExceptionController.php

@@ -78,8 +78,10 @@ public function execute(FlattenException $exception, Request $request) {
   /**
    * Processes a MethodNotAllowed exception into an HTTP 405 response.
    *
-   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
-   *   The Event to process.
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
+   *   The flattened exception.
+   * @param Symfony\Component\HttpFoundation\Request $request
+   *   The request object that triggered this exception.
    */
   public function on405Html(FlattenException $exception, Request $request) {
     $event->setResponse(new Response('Method Not Allowed', 405));
@@ -88,8 +90,10 @@ public function on405Html(FlattenException $exception, Request $request) {
   /**
    * Processes an AccessDenied exception into an HTTP 403 response.
    *
-   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
-   *   The Event to process.
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
+   *   The flattened exception.
+   * @param Symfony\Component\HttpFoundation\Request $request
+   *   The request object that triggered this exception.
    */
   public function on403Html(FlattenException $exception, Request $request) {
     $system_path = $request->attributes->get('system_path');
@@ -115,8 +119,8 @@ public function on403Html(FlattenException $exception, Request $request) {
       //   reset that are not triggering test failures right now.  If found,
       //   add them here.
       // @todo Refactor the breadcrumb system so that it does not rely on static
-      // variables in the first place, which will eliminate the need for this
-      // hack.
+      //   variables in the first place, which will eliminate the need for this
+      //   hack.
       drupal_static_reset('menu_set_active_trail');
       menu_reset_static_cache();
 
@@ -140,10 +144,12 @@ public function on403Html(FlattenException $exception, Request $request) {
   }
 
   /**
-   * Processes a NotFound exception into an HTTP 403 response.
+   * Processes a NotFound exception into an HTTP 404 response.
    *
-   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
-   *   The Event to process.
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
+   *   The flattened exception.
+   * @param Sonfony\Component\HttpFoundation\Request $request
+   *   The request object that triggered this exception.
    */
   public function on404Html(FlattenException $exception, Request $request) {
     watchdog('page not found', check_plain($request->attributes->get('system_path')), NULL, WATCHDOG_WARNING);
@@ -178,8 +184,8 @@ public function on404Html(FlattenException $exception, Request $request) {
       //   reset that are not triggering test failures right now.  If found,
       //   add them here.
       // @todo Refactor the breadcrumb system so that it does not rely on static
-      // variables in the first place, which will eliminate the need for this
-      // hack.
+      //   variables in the first place, which will eliminate the need for this
+      //   hack.
       drupal_static_reset('menu_set_active_trail');
       menu_reset_static_cache();
 
@@ -205,7 +211,7 @@ public function on404Html(FlattenException $exception, Request $request) {
   /**
    * Processes a generic exception into an HTTP 500 response.
    *
-   * @param FlattenException $exception
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
    *   Metadata about the exception that was thrown.
    * @param Symfony\Component\HttpFoundation\Request $request
    *   The request object that triggered this exception.
@@ -267,10 +273,12 @@ public function on500Html(FlattenException $exception, Request $request) {
   }
 
   /**
-   * Processes an AccessDenied exception into an HTTP 403 response.
+   * Processes an AccessDenied exception that occured on a JSON request.
    *
-   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
-   *   The Event to process.
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
+   *   The flattened exception.
+   * @param Symfony\Component\HttpFoundation\Request $request
+   *   The request object that triggered this exception.
    */
   public function on403Json(FlattenException $exception, Request $request) {
     $response = new JsonResponse();
@@ -279,10 +287,12 @@ public function on403Json(FlattenException $exception, Request $request) {
   }
 
   /**
-   * Processes a NotFound exception into an HTTP 404 response.
+   * Processes a NotFound exception that occured on a JSON request.
    *
-   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
-   *   The Event to process.
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
+   *   The flattened exception.
+   * @param Symfony\Component\HttpFoundation\Request $request
+   *   The request object that triggered this exception.
    */
   public function on404Json(FlattenException $exception, Request $request) {
     $response = new JsonResponse();
@@ -291,10 +301,12 @@ public function on404Json(FlattenException $exception, Request $request) {
   }
 
   /**
-   * Processes a MethodNotAllowed exception into an HTTP 405 response.
+   * Processes a MethodNotAllowed exception that occured on a JSON request.
    *
-   * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
-   *   The Event to process.
+   * @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
+   *   The flattened exception.
+   * @param Symfony\Component\HttpFoundation\Request $request
+   *   The request object that triggered this exception.
    */
   public function on405Json(FlattenException $exception, Request $request) {
     $response = new JsonResponse();

core/lib/Drupal/Core/StreamWrapper/LocalStream.php

@@ -44,7 +44,8 @@ abstract class LocalStream implements StreamWrapperInterface {
 
   /**
    * Gets the path that the wrapper is responsible for.
-   * @todo: Review this method name in D8 per http://drupal.org/node/701358
+   *
+   * @todo Review this method name in D8 per http://drupal.org/node/701358.
    *
    * @return string
    *   String specifying the path.

core/lib/Drupal/Core/Updater/Updater.php

@@ -213,7 +213,7 @@ public function update(&$filetransfer, $overrides = array()) {
       $this->makeWorldReadable($filetransfer, $args['install_dir'] . '/' . $this->name);
 
       // Run the updates.
-      // @todo: decide if we want to implement this.
+      // @todo Decide if we want to implement this.
       $this->postUpdate();
 
       // For now, just return a list of links of things to do.