Commit 171fdb44 authored by Niklas Fiekas's avatar Niklas Fiekas Committed by Crell

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

parent 270dcd2e
...@@ -1537,15 +1537,17 @@ function request_uri($omit_query_string = FALSE) { ...@@ -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. * @todo Replace this function with a proper dependency injection container.
* *
* @staticvar Request $request * @staticvar Symfony\Component\HttpFoundation\Request $request
* @param Request $new_request *
* The new request object to store. If you are not index.php, you probably * @param Symfony\Component\HttpFoundation\Request $new_request
* should not be using this parameter. * Optional. The new request object to store. This parameter should only be
* @return Request * used by index.php.
*
* @return Symfony\Component\HttpFoundation\Request
* The current request object. * The current request object.
*/ */
function request(Request $new_request = NULL) { function request(Request $new_request = NULL) {
......
...@@ -480,10 +480,10 @@ function install_run_task($task, &$install_state) { ...@@ -480,10 +480,10 @@ function install_run_task($task, &$install_state) {
include_once DRUPAL_ROOT . '/core/includes/batch.inc'; include_once DRUPAL_ROOT . '/core/includes/batch.inc';
$output = _batch_page(); $output = _batch_page();
// Because Batch API now returns a JSON response for intermediary steps, // Because Batch API now returns a JSON response for intermediary steps,
// but the installer doesn't handle Response objects yet, we will just // but the installer doesn't handle Response objects yet, just send the
// send the output here and emulate the old model. // output here and emulate the old model.
// @todo: Replace this when we refactor the installer to use a // @todo Replace this when we refactor the installer to use a request-
// Request/Response workflow. // response workflow.
if ($output instanceof Response) { if ($output instanceof Response) {
$output->send(); $output->send();
$output = NULL; $output = NULL;
......
...@@ -13,21 +13,24 @@ ...@@ -13,21 +13,24 @@
* This class is a central library for content type negotiation. * This class is a central library for content type negotiation.
* *
* @todo Replace this class with a real content negotiation library based on * @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 { 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 * 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. * The request object from which to extract the content type.
*
* @return
* The normalized type of a given request.
*/ */
public function getContentType(Request $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>. // response wrapped in <textarea>.
if ($request->get('ajax_iframe_upload', FALSE)) { if ($request->get('ajax_iframe_upload', FALSE)) {
return 'iframeupload'; return 'iframeupload';
...@@ -48,6 +51,4 @@ public function getContentType(Request $request) { ...@@ -48,6 +51,4 @@ public function getContentType(Request $request) {
// Do HTML last so that it always wins. // Do HTML last so that it always wins.
return 'html'; return 'html';
} }
} }
...@@ -524,10 +524,9 @@ public function query($query, array $args = array(), $options = array()) { ...@@ -524,10 +524,9 @@ public function query($query, array $args = array(), $options = array()) {
} }
catch (PDOException $e) { catch (PDOException $e) {
if ($options['throw_exception']) { if ($options['throw_exception']) {
// Wrap the exception in another exception. Its message is the extra // Wrap the exception in another exception, because PHP does not allow
// database debug information. We have to do it this way because PHP // overriding Exception::getMessage(). Its message is the extra database
// does not allow us to override Exception::getMessage(). // debug information.
$query_string = ($query instanceof DatabaseStatementInterface) ? $stmt->getQueryString() : $query; $query_string = ($query instanceof DatabaseStatementInterface) ? $stmt->getQueryString() : $query;
$message = $e->getMessage() . ": " . $query_string . "; " . print_r($args, TRUE); $message = $e->getMessage() . ": " . $query_string . "; " . print_r($args, TRUE);
$exception = new DatabaseExceptionWrapper($message, 0, $e); $exception = new DatabaseExceptionWrapper($message, 0, $e);
......
...@@ -2,7 +2,6 @@ ...@@ -2,7 +2,6 @@
/** /**
* @file * @file
*
* Definition of Drupal\Core\DrupalKernel. * Definition of Drupal\Core\DrupalKernel.
*/ */
...@@ -17,7 +16,6 @@ ...@@ -17,7 +16,6 @@
use Symfony\Component\EventDispatcher\Event; use Symfony\Component\EventDispatcher\Event;
use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface; use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent; use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
//use Symfony\Component\HttpKernel\EventListener\RouterListener;
use Symfony\Component\HttpKernel\EventListener\ExceptionListener; use Symfony\Component\HttpKernel\EventListener\ExceptionListener;
use Drupal\Core\EventSubscriber\ViewSubscriber; use Drupal\Core\EventSubscriber\ViewSubscriber;
use Drupal\Core\EventSubscriber\AccessSubscriber; use Drupal\Core\EventSubscriber\AccessSubscriber;
...@@ -39,25 +37,25 @@ class DrupalKernel extends HttpKernel { ...@@ -39,25 +37,25 @@ class DrupalKernel extends HttpKernel {
/** /**
* The event dispatcher used by this kernel. * The event dispatcher used by this kernel.
* *
* @var EventDispatcherInterface * @var Symfony\Component\EventDispatcher\EventDispatcherInterface
*/ */
protected $dispatcher; protected $dispatcher;
/** /**
* The controller resolver that will extract the controller from a Request. * The controller resolver that will extract the controller from a Request.
* *
* @var ControllerResolverInterface * @var Symfony\Component\HttpKernel\Controller\ControllerResolverInterface
*/ */
protected $resolver; protected $resolver;
/** /**
* Constructor * Constructor.
* *
* @param EventDispatcherInterface $dispatcher * @param Symfony\Component\EventDispatcher\EventDispatcherInterface $dispatcher
* An EventDispatcherInterface instance * An EventDispatcherInterface instance.
* @param ControllerResolverInterface $resolver * @param Symfony\Component\HttpKernel\Controller\ControllerResolverInterface $resolver
* A ControllerResolverInterface instance * A ControllerResolverInterface instance.
*/ */
public function __construct(EventDispatcherInterface $dispatcher, ControllerResolverInterface $resolver) { public function __construct(EventDispatcherInterface $dispatcher, ControllerResolverInterface $resolver) {
parent::__construct($dispatcher, $resolver); parent::__construct($dispatcher, $resolver);
...@@ -71,7 +69,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso ...@@ -71,7 +69,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso
// @todo Make this extensible rather than just hard coding some. // @todo Make this extensible rather than just hard coding some.
// @todo Add a subscriber to handle other things, too, like our Ajax // @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 ViewSubscriber($negotiation));
$this->dispatcher->addSubscriber(new AccessSubscriber()); $this->dispatcher->addSubscriber(new AccessSubscriber());
$this->dispatcher->addSubscriber(new MaintenanceModeSubscriber()); $this->dispatcher->addSubscriber(new MaintenanceModeSubscriber());
...@@ -82,7 +80,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso ...@@ -82,7 +80,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso
$this->dispatcher->addSubscriber(new RequestCloseSubscriber()); $this->dispatcher->addSubscriber(new RequestCloseSubscriber());
// Some other form of error occured that wasn't handled by another kernel // 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. // 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. // 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 // By default, this will be an HTML-type response because that's a decent
......
...@@ -13,8 +13,7 @@ ...@@ -13,8 +13,7 @@
/** /**
* @file * @file
* * Definition of Drupal\Core\EventSubscriber\AccessSubscriber.
* Definition of Drupal\Core\EventSubscriber\AccessSubscriber
*/ */
/** /**
...@@ -26,9 +25,9 @@ class AccessSubscriber implements EventSubscriberInterface { ...@@ -26,9 +25,9 @@ class AccessSubscriber implements EventSubscriberInterface {
* Verifies that the current user can access the requested path. * Verifies that the current user can access the requested path.
* *
* @todo This is a total hack to keep our current access system working. It * @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. * The Event to process.
*/ */
public function onKernelRequestAccessCheck(GetResponseEvent $event) { public function onKernelRequestAccessCheck(GetResponseEvent $event) {
......
...@@ -19,7 +19,7 @@ class FinishResponseSubscriber implements EventSubscriberInterface { ...@@ -19,7 +19,7 @@ class FinishResponseSubscriber implements EventSubscriberInterface {
/** /**
* Sets extra headers on successful responses. * Sets extra headers on successful responses.
* *
* @param FilterResponseEvent $event * @param Symfony\Component\HttpKernel\Event\FilterResponseEvent $event
* The event to process. * The event to process.
*/ */
public function onRespond(FilterResponseEvent $event) { public function onRespond(FilterResponseEvent $event) {
......
<?php <?php
/**
* @file
* Definition of Drupal\Core\EventSubscriber\MaintenanceModeSubscriber.
*/
namespace Drupal\Core\EventSubscriber; namespace Drupal\Core\EventSubscriber;
use Symfony\Component\HttpFoundation\Response; use Symfony\Component\HttpFoundation\Response;
...@@ -7,11 +12,6 @@ ...@@ -7,11 +12,6 @@
use Symfony\Component\HttpKernel\Event\GetResponseEvent; use Symfony\Component\HttpKernel\Event\GetResponseEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/**
* @file
* Definition of Drupal\Core\EventSubscriber\MaintenanceModeSubscriber.
*/
/** /**
* Maintenance mode subscriber for controller requests. * Maintenance mode subscriber for controller requests.
*/ */
...@@ -20,7 +20,7 @@ class MaintenanceModeSubscriber implements EventSubscriberInterface { ...@@ -20,7 +20,7 @@ class MaintenanceModeSubscriber implements EventSubscriberInterface {
/** /**
* Response with the maintenance page when the site is offline. * Response with the maintenance page when the site is offline.
* *
* @param GetResponseEvent $event * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process. * The Event to process.
*/ */
public function onKernelRequestMaintenanceModeCheck(GetResponseEvent $event) { public function onKernelRequestMaintenanceModeCheck(GetResponseEvent $event) {
......
...@@ -27,5 +27,4 @@ public function setPath(Request $request, $path) { ...@@ -27,5 +27,4 @@ public function setPath(Request $request, $path) {
// object directly. // object directly.
_current_path($path); _current_path($path);
} }
} }
...@@ -2,8 +2,7 @@ ...@@ -2,8 +2,7 @@
/** /**
* @file * @file
* * Definition of Drupal\Core\EventSubscriber\PathSubscriber.
* Definition of Drupal\Core\EventSubscriber\PathSubscriber
*/ */
namespace Drupal\Core\EventSubscriber; namespace Drupal\Core\EventSubscriber;
...@@ -21,14 +20,13 @@ class PathSubscriber extends PathListenerBase implements EventSubscriberInterfac ...@@ -21,14 +20,13 @@ class PathSubscriber extends PathListenerBase implements EventSubscriberInterfac
/** /**
* Resolve the system path. * Resolve the system path.
* *
* @todo The path system should be objectified to remove the function calls * @todo The path system should be objectified to remove the function calls in
* in this method. * this method.
* *
* @param GetResponseEvent $event * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process. * The Event to process.
*/ */
public function onKernelRequestPathResolve(GetResponseEvent $event) { public function onKernelRequestPathResolve(GetResponseEvent $event) {
$request = $event->getRequest(); $request = $event->getRequest();
$path = $this->extractPath($request); $path = $this->extractPath($request);
...@@ -41,10 +39,10 @@ public function onKernelRequestPathResolve(GetResponseEvent $event) { ...@@ -41,10 +39,10 @@ public function onKernelRequestPathResolve(GetResponseEvent $event) {
/** /**
* Resolve the front-page default path. * Resolve the front-page default path.
* *
* @todo The path system should be objectified to remove the function calls * @todo The path system should be objectified to remove the function calls in
* in this method. * this method.
* *
* @param GetResponseEvent $event * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process. * The Event to process.
*/ */
public function onKernelRequestFrontPageResolve(GetResponseEvent $event) { public function onKernelRequestFrontPageResolve(GetResponseEvent $event) {
...@@ -63,10 +61,9 @@ public function onKernelRequestFrontPageResolve(GetResponseEvent $event) { ...@@ -63,10 +61,9 @@ public function onKernelRequestFrontPageResolve(GetResponseEvent $event) {
* Decode language information embedded in the request path. * Decode language information embedded in the request path.
* *
* @todo Refactor this entire method to inline the relevant portions of * @todo Refactor this entire method to inline the relevant portions of
* drupal_language_initialize(). See the inline comment for more * drupal_language_initialize(). See the inline comment for more details.
* details.
* *
* @param GetResponseEvent $event * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process. * The Event to process.
*/ */
public function onKernelRequestLanguageResolve(GetResponseEvent $event) { public function onKernelRequestLanguageResolve(GetResponseEvent $event) {
...@@ -93,15 +90,15 @@ 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 * Parameters in the URL sometimes represent code-meaningful strings. It is
* therefore useful to always urldecode() those values so that individual * therefore useful to always urldecode() those values so that individual
* controllers need not concern themselves with it. This is Drupal-specific * controllers need not concern themselves with it. This is Drupal-specific
* logic, and may not be familiar for developers used to other Symfony-family * logic and may not be familiar for developers used to other Symfony-family
* projects. * projects.
* *
* @todo Revisit whether or not this logic is appropriate for here or if * @todo Revisit whether or not this logic is appropriate for here or if
* controllers should be required to implement this logic themselves. If * controllers should be required to implement this logic themselves. If we
* we decide to keep this code, remove this TODO. * decide to keep this code, remove this TODO.
* *
* @param GetResponseEvent $event * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process. * The Event to process.
*/ */
public function onKernelRequestDecodePath(GetResponseEvent $event) { public function onKernelRequestDecodePath(GetResponseEvent $event) {
......
<?php <?php
/**
* @file
* Definition of Drupal\Core\EventSubscriber\RequestCloseSubscriber.
*/
namespace Drupal\Core\EventSubscriber; namespace Drupal\Core\EventSubscriber;
use Symfony\Component\HttpKernel\KernelEvents; use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\HttpKernel\Event\PostResponseEvent; use Symfony\Component\HttpKernel\Event\PostResponseEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/**
* @file
*
* Definition of Drupal\Core\EventSubscriber\RequestCloseSubscriber;
*/
/** /**
* Subscriber for all responses. * Subscriber for all responses.
*/ */
...@@ -22,16 +20,16 @@ class RequestCloseSubscriber implements EventSubscriberInterface { ...@@ -22,16 +20,16 @@ class RequestCloseSubscriber implements EventSubscriberInterface {
* Performs end of request tasks. * Performs end of request tasks.
* *
* @todo The body of this function has just been copied almost verbatim from * @todo The body of this function has just been copied almost verbatim from
* drupal_page_footer(), with the exception of now passing the response * 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 * content to drupal_page_set_cache(). There's probably a lot in here that
* needs to get removed/changed. * needs to get removed/changed.
* *
* @param PostResponseEvent $event * @param Symfony\Component\HttpKernel\Event\PostResponseEvent $event
* The Event to process. * The Event to process.
*/ */
public function onTerminate(PostResponseEvent $event) { public function onTerminate(PostResponseEvent $event) {
global $user; global $user;
module_invoke_all('exit'); module_invoke_all('exit');
// Commit the user session, if needed. // Commit the user session, if needed.
......
...@@ -2,7 +2,6 @@ ...@@ -2,7 +2,6 @@
/** /**
* @file * @file
*
* Definition of Drupal\Core\EventSubscriber\RouterListener; * Definition of Drupal\Core\EventSubscriber\RouterListener;
*/ */
...@@ -17,7 +16,6 @@ ...@@ -17,7 +16,6 @@
use Symfony\Component\Routing\Exception\ResourceNotFoundException; use Symfony\Component\Routing\Exception\ResourceNotFoundException;
use Symfony\Component\Routing\Exception\MethodNotFoundException; use Symfony\Component\Routing\Exception\MethodNotFoundException;
/** /**
* Drupal-specific Router listener. * Drupal-specific Router listener.
* *
...@@ -40,7 +38,7 @@ public function __construct(UrlMatcherInterface $urlMatcher, LoggerInterface $lo ...@@ -40,7 +38,7 @@ public function __construct(UrlMatcherInterface $urlMatcher, LoggerInterface $lo
* This method is nearly identical to the parent, except it passes the * This method is nearly identical to the parent, except it passes the
* $request->attributes->get('system_path') variable to the matcher. * $request->attributes->get('system_path') variable to the matcher.
* That is where Drupal stores its processed, de-aliased, and sanitized * 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. * since we want attributes to be available to the matcher and to controllers.
*/ */
public function onKernelRequest(GetResponseEvent $event) { public function onKernelRequest(GetResponseEvent $event) {
...@@ -80,5 +78,4 @@ public function onKernelRequest(GetResponseEvent $event) { ...@@ -80,5 +78,4 @@ public function onKernelRequest(GetResponseEvent $event) {
throw new MethodNotAllowedHttpException($e->getAllowedMethods(), $message, $e); throw new MethodNotAllowedHttpException($e->getAllowedMethods(), $message, $e);
} }
} }
} }
<?php <?php
/**
* @file
* Definition of Drupal\Core\EventSubscriber\ViewSubscriber.
*/
namespace Drupal\Core\EventSubscriber; namespace Drupal\Core\EventSubscriber;
use Symfony\Component\HttpFoundation\Response; use Symfony\Component\HttpFoundation\Response;
...@@ -14,12 +19,6 @@ ...@@ -14,12 +19,6 @@
use Drupal\Core\ContentNegotiation; use Drupal\Core\ContentNegotiation;
/**
* @file
*
* Definition of Drupal\Core\EventSubscriber\ViewSubscriber;
*/
/** /**
* Main subscriber for VIEW HTTP responses. * Main subscriber for VIEW HTTP responses.
*/ */
...@@ -40,7 +39,7 @@ public function __construct(ContentNegotiation $negotiation) { ...@@ -40,7 +39,7 @@ public function __construct(ContentNegotiation $negotiation) {
* from an JSON-type response is a JSON string, so just wrap it into a * from an JSON-type response is a JSON string, so just wrap it into a
* Response object. * Response object.
* *
* @param GetResponseEvent $event * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process. * The Event to process.
*/ */
public function onView(GetResponseEvent $event) { public function onView(GetResponseEvent $event) {
...@@ -60,8 +59,6 @@ public function onView(GetResponseEvent $event) { ...@@ -60,8 +59,6 @@ public function onView(GetResponseEvent $event) {
public function onJson(GetResponseEvent $event) { public function onJson(GetResponseEvent $event) {
$page_callback_result = $event->getControllerResult(); $page_callback_result = $event->getControllerResult();
//print_r($page_callback_result);
$response = new JsonResponse(); $response = new JsonResponse();
$response->setContent($page_callback_result); $response->setContent($page_callback_result);
...@@ -104,12 +101,12 @@ public function onIframeUpload(GetResponseEvent $event) { ...@@ -104,12 +101,12 @@ public function onIframeUpload(GetResponseEvent $event) {
* Processes a successful controller into an HTTP 200 response. * Processes a successful controller into an HTTP 200 response.
* *
* Some controllers may not return a response object but simply the body of * 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 * 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 * body into a Response object. In particular we assume that the return from
* from an HTML-type response is a render array from a legacy page callback * an HTML-type response is a render array from a legacy page callback and
* and render it. * render it.
* *
* @param GetResponseEvent $event * @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process. * The Event to process.
*/