DrupalKernel::guessApplicationRoot() should document what the assumptions are and what it's doing

Hi @joachim

Are the comments in the attached patch correct? Do they cover this or is there more to say?

Thanks.

Oops, sorry. Initial docblock wasn't quite right. New patch attached. (Didn't bother with interdiff, since this is small).

Or perhaps the attached is better?

I agree, I think this is a good idea to add the assumptions in the documentation of this method.

+++ b/core/lib/Drupal/Core/DrupalKernel.php
@@ -299,10 +299,21 @@ public function __construct($environment, $class_loader, $allow_dumping = TRUE,
    * Determine the application root directory based on assumptions.
    *
+   * This implementation assumes that the application root is two levels
+   * higher in the directory structure than the PSR-4 base directory (i.e. two
+   * levels up from the path to this class in the filesystem minus it's
+   * namespace).
...
+    // Guess the application root by:
+    //
+    // - removing the namespace directories from the path
+    // - getting the path to the directory two levels up from the path
+    //   determined in the previous step.

I don't think repeating the documentation about the implementation helps. It means that if we can the implementation we have to change documentation. I think what I'd do is change Determine the application root directory based on assumptions. to Determine the application root directory based on this file's location. and then only have the inline comments next to the code as the implementation is probably not that important to the caller.

The inline comments current don't obey the API docs standard - there is no empty line in-between the colon and that first hyphen. See https://www.drupal.org/docs/develop/coding-standards/api-documentation-a...

This patch might fulfil the requirements.

The suggestion in #9 doesn't do what @alexpott suggested in #8.

Here's a fresh patch after the changes.

Here is a patch as per suggestion in #8 by @alexpott.

Committed 03a3058 and pushed to 8.7.x and 8.6.x. Thanks!