Add and improve documentation.

core/lib/Drupal/Core/ContentNegotiation.php

 <?php
 
+/**
+ * @file
+ * Definition of Drupal\Core\ContentNegotiation.
+ */
+
 namespace Drupal\Core;
 
 use Symfony\Component\HttpFoundation\Request;
 
 /**
- * Description of ContentNegotiation
+ * 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.
  */
 class ContentNegotiation {
 
+  /**
+   * Returns the normalized type of a given request.
+   *
+   * The normalized type is a short, lowercase version of the format, such as
+   * "html" or "json" or "atom".
+   *
+   * @param Request $request
+   *   The request object from which to extract the content type.
+   */
   public function getContentType(Request $request) {
     $acceptable_content_types = $request->getAcceptableContentTypes();
-    if (in_array('application/json', $request->getAcceptableContentTypes())) {
+    if (in_array('application/json', $acceptable_content_types)) {
       return 'json';
     }
+
+    // Do HTML last so that it always wins for */* formats.
     if(in_array('text/html', $acceptable_content_types) || in_array('*/*', $acceptable_content_types)) {
       return 'html';
     }

core/lib/Drupal/Core/DrupalKernel.php

 <?php
 
+/**
+ * @file
+ *
+ * Definition of Drupal\Core\DrupalKernel.
+ */
+
 namespace Drupal\Core;
 
 use Symfony\Component\HttpFoundation\Request;
@@ -21,26 +27,32 @@
 use Exception;
 
 /**
- * @file
- *
- * Definition of Drupal\Core\DrupalKernel.
- */
-
-/**
- * The DrupalApp class is the core of Drupal itself.
+ * The DrupalKernel class is the core of Drupal itself.
  */
 class DrupalKernel extends HttpKernel {
+
+    /**
+     * The event dispatcher used by this kernel.
+     *
+     * @var EventDispatcherInterface
+     */
     protected $dispatcher;
+
+    /**
+     * The controller resolver that will extract the controller from a Request.
+     *
+     * @var ControllerResolverInterface
+     */
     protected $resolver;
 
 
     /**
      * Constructor
      *
-     * @param EventDispatcherInterface    $dispatcher An EventDispatcherInterface instance
-     * @param ControllerResolverInterface $resolver   A ControllerResolverInterface instance
-     *
-     * @api
+     * @param EventDispatcherInterface $dispatcher
+     *   An EventDispatcherInterface instance
+     * @param ControllerResolverInterface $resolver
+     *   A ControllerResolverInterface instance
      */
    public function __construct(EventDispatcherInterface $dispatcher, ControllerResolverInterface $resolver) {
       parent::__construct($dispatcher, $resolver);

core/lib/Drupal/Core/ExceptionController.php

 <?php
 
+/**
+ * @file
+ *
+ * Definition of Drupal\Core\ExceptionController.
+ */
 
 namespace Drupal\Core;
 
@@ -14,19 +19,51 @@
 use Exception;
 
 /**
- * Description of ExceptionController
- *
+ * This controller handles HTTP errors generated by the routing system.
  */
 class ExceptionController {
 
+  /**
+   * The kernel that spawned this controller.
+   *
+   * We will use this to fire subrequests as needed.
+   *
+   * @var HttpKernelInterface
+   */
   protected $kernel;
+
+  /**
+   * The
+   *
+   * @var ContentNegotiation
+   */
   protected $negotiation;
 
+  /**
+   * Constructor
+   * 
+   * @param HttpKernelInterface $kernel
+   *   The kernel that spawned this controller, so that it can be reused
+   *   for subrequests.
+   * @param ContentNegotiation $negotiation
+   *   The content negotiation library to use to determine the correct response
+   *   format.
+   */
   public function __construct(HttpKernelInterface $kernel, ContentNegotiation $negotiation) {
     $this->kernel = $kernel;
     $this->negotiation = $negotiation;
   }
 
+  /**
+   * Handles an exception on a request.
+   *
+   * @param FlattenException $exception
+   *   The flattened exception.
+   * @param Request $request
+   *   The request that generated the exception.
+   * @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);
@@ -85,6 +122,12 @@ public function on403Html(FlattenException $exception, Request $request) {
     return $response;
   }
 
+  /**
+   * Processes a NotFound exception into an HTTP 403 response.
+   *
+   * @param GetResponseEvent $event
+   *   The Event to process.
+   */
   public function on404Html(FlattenException $exception, Request $request) {
     watchdog('page not found', check_plain($_GET['q']), NULL, WATCHDOG_WARNING);
 

core/lib/Drupal/Core/UrlMatcher.php

 <?php
 
+/**
+ * @file
+ *
+ * Definition of Drupal\Core\UrlMatcher.
+ */
+
 namespace Drupal\Core;
 
 use Symfony\Component\Routing\Exception\MethodNotAllowedException;
@@ -14,6 +20,11 @@
  */
 class UrlMatcher extends SymfonyUrlMatcher {
 
+  /**
+   * The request context for this matcher.
+   *
+   * @var RequestContext
+   */
   protected $context;
 
   /**