Small doc cleanup for the new kernel

This is mostly OK, but:

+++ b/core/lib/Drupal/Core/EventSubscriber/MaintenanceModeSubscriber.php
@@ -18,7 +18,7 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 class MaintenanceModeSubscriber implements EventSubscriberInterface {
 
   /**
-   * Response with the maintenance page when the site is offline.
+   * Responses with the maintenance page when the site is offline.

Response -> Responds

Also, I don't think this belongs in a documentation-only patch:

+++ b/core/includes/bootstrap.inc
@@ -1,10 +1,10 @@
 <?php
 
-use Drupal\Core\Database\Database;
 use Symfony\Component\ClassLoader\UniversalClassLoader;
 use Symfony\Component\ClassLoader\ApcUniversalClassLoader;
-use Drupal\Core\DependencyInjection\ContainerBuilder;
 use Symfony\Component\HttpFoundation\Request;
+use Drupal\Core\Database\Database;
+use Drupal\Core\DependencyInjection\ContainerBuilder;

And of course, there are the ToDos...

No, you don't have to open a separate issue, but why is it necessary or desirable to do it at all?

RE #4 - I think you should therefore file a separate coding standards issue saying "use statements should always be grouped", and search through core and do this and any other files that violate it together. Documentation component patches should be limited to documentation.

I really want to see these docs fixes landing. Thanks aspilicious!

The patch was no longer applying. Rebased it. Fixed the TODOs and a few more things I found.

These all look good to me.

aspilicious, can you open another issue and link it here about use-ordering? (I agree with having a sane order for them rather than willy-nilly.)

Before I commit this, I just want to double-check on this one hunk:

-    // Browser IFRAMEs expect HTML. Browser extensions, such as Linkification
-    // and Skype's Browser Highlighter, convert URLs, phone numbers, etc. into
-    // links. This corrupts the JSON response. Protect the integrity of the
-    // JSON data by making it the value of a textarea.
-    // @see http://malsup.com/jquery/form/#file-upload
-    // @see http://drupal.org/node/1009382
     $html = '<textarea>' . $json . '</textarea>';

I'm not sure why these in-code comments were removed (they weren't replaced by anything)?

Oh I see, it's part of the function documentation... There, it doesn't make sense to me, as written. The function doc says:

+  /**
+   * Processes a controller result into an AJAX response wrapped in a textarea.
+   *
+   * Browser IFRAMEs expect HTML. Browser extensions such as Linkification and
+   * Skype's browser highlighter convert URLs, phone numbers, etc. into links.
+   * This corrupts the JSON response. Protect the integrity of the JSON data by
+   * making it the value of a textarea.

"Protect the integrity..." -- the last sentence is confusing, because it's not clear whether you're telling people calling the function to do this, or saying that the function does this. It should probably say "This function protects the integrity...".

Should be a quick reroll to fix that...

Yep, thanks @jhodgdon. That makes sense. This should make a bit clearer, that it's not the responsibility of the caller. (I'd like to move it to the method documentation, because it's really not an implementation detail of that method, but instead the whole reason for it's existence.)

Reroll. My above file accidantely was based on an experimental branch I used to test https://github.com/symfony/symfony/pull/4546.

I took a very careful look at the added documentation... This is looking pretty good, but I think it could be made quite a bit better by improving the @return statements. Generically, @return statements on functions/methods should explain what is returned and how it is related to the parameters. Some of the @return statements in this patch could be improved:

a) There are several functions whose @return section follows this model:

...
+   * @return Symfony\Component\HttpFoundation\Response
+   *   A response.
    */
   public function onView(GetResponseEvent $event) {
...
+   * @return Symfony\Component\HttpFoundation\JsonResponse
+   *   A JSON response.
+   */
   public function onJson(GetResponseEvent $event) {
...
+++ b/core/lib/Drupal/Core/ExceptionController.php
+   * @return Symfony\Component\HttpFoundation\Response
+   *   A response object to be sent to the server.
    */
   public function on403Html(FlattenException $exception, Request $request) {
// etc.

That @return documentation would be better if it explained what type of response it is (AJAX? 404? HTTP? ???), and what it means. For example, this method:

+   * @return Symfony\Component\HttpFoundation\Response
+   *   A response.
+   *
+   * @see http://malsup.com/jquery/form/#file-upload
+   * @see http://drupal.org/node/1009382
+   */
   public function onIframeUpload(GetResponseEvent $event) {

I think it should probably say "An AJAX response for the controller result, wrapped in a textarea element.".

b)

+++ b/core/lib/Drupal/Core/ExceptionController.php
...
+   * @return array
    *   An associative array with keys 'file', 'line' and 'function'.
    */
   protected function getLastCaller($backtrace) {

This leaves me wondering what the array represents? It should probably say "An associative array of information about the last function that called [whatever it is], with elements 'file', 'line', and 'function'.".

Re-roll to let re-apply on current upstream. It still needs to add suggestion from #15.

I'm closing very old coding standards fixup issues. They are being addressed on other issues mostly.