diff -u b/core/lib/Drupal/Core/Url.php b/core/lib/Drupal/Core/Url.php
--- b/core/lib/Drupal/Core/Url.php
+++ b/core/lib/Drupal/Core/Url.php
@@ -41,13 +41,46 @@
use DependencySerializationTrait;
/**
- * Scheme for base-relative, unrouted URIs.
+ * Scheme for URIs to resolve as references relative to Drupal's installation.
*
- * This scheme should only be used for unrouted URIs, like base:robots.txt
- * or base:core/update.php. To create such a base-relative URI from a path,
- * use Url::fromBaseRelativePath(). To create a host-relative URI instead
- * (for example, for http://example.com/index.html when Drupal is installed
- * in http://example.com/drupal/), use Url::fromHostRelativePath().
+ * https://tools.ietf.org/html/rfc3986#section-5.2 specifies the standard for
+ * resolving URI references relative to a base URI.
+ *
+ * This scheme is to allow such references to be internally represented and
+ * managed in Drupal as full URIs themselves, and resolved to the
+ * corresponding URLs at runtime. When performing this resolution, the base
+ * URI is Drupal's installation URL.
+ *
+ * For example, if Drupal is installed in http://example.com/drupal/, then:
+ * - Url::fromUri(Url::SCHEME_BASE . ':README.txt')->toString() would return
+ * '/drupal/README.txt'.
+ * - Url::fromUri(Url::SCHEME_BASE . ':/index.html')->toString() would return
+ * '/index.html'.
+ *
+ * This is the identical resolution as what a browser would perform if Drupal
+ * output a @link http://www.w3.org/wiki/HTML/Elements/base @endlink
+ * element and the above URLs were written within links as:
+ * - (browser resolves as '/drupal/README.txt')
+ * - (browser resolves as '/index.html')
+ *
+ * The examples above can also be generated from the wrapper methods
+ * fromBaseRelativePath() and fromHostRelativePath(), as follows:
+ * - Url::fromBaseRelativePath('README.txt') is equivalent to
+ * Url::fromUri(Url::SCHEME_BASE . ':README.txt').
+ * - Url::fromHostRelativePath('index.html') is equivalent to
+ * Url::fromUri(Url::SCHEME_BASE . ':/index.html').
+ *
+ * Note that this scheme is intended for linking to non-Drupal-routed pages.
+ * For example, to static files or to pages served by other software on the
+ * website. As such, the resolution of this scheme does not apply any path
+ * processors, such as language prefixing and alias lookup, or access
+ * checking (->access() returns TRUE for URIs in this scheme). Therefore,
+ * using this scheme for Drupal-routed pages is incompatible with
+ * multilingual sites, with search engine optimization, and with hiding links
+ * to pages that the user can't access, unless you take care of all that
+ * yourself. For these reasons, it is recommended to not use this scheme for
+ * pages served by Drupal. The other schemes and their wrapper methods
+ * can be used for that.
*
* @see static::fromBaseRelativePath()
* @see static::fromHostRelativePath()
@@ -253,11 +286,12 @@
*
* This method should only be used for paths within the base directory of the
* site installation that do not have a Drupal route. These may be files like
- * robots.txt, core scripts like core/update.php, or they may be another
+ * robots.txt, core scripts like core/install.php, or they may be another
* application placed within the Drupal site installation.
*
- * Do not use this method for URLs that do have a Drupal route (such as pages
- * generated by Drupal) because this will circumvent the routing system.
+ * Do not use this method for URLs that have a Drupal route (that is, most
+ * pages generated by Drupal). See the documentation of static::SCHEME_BASE
+ * for details.
*
* @param string $path
* The base-relative path, for example 'robots.txt'.
@@ -265,9 +299,10 @@
* (optional) An array of options. See static::fromUri() for details.
*
* @return \Drupal\Core\Url
- * A new Url object for an unrouted, base-relative URL not internal to
- * Drupal, but within the site installation directory.
+ * A new Url object for an unrouted URL within the site installation
+ * directory.
*
+ * @see static::SCHEME_BASE
* @see static::fromHostRelativePath()
* @see static::fromUri()
* @see static::fromRoute()
@@ -282,8 +317,9 @@
* This method should only be used for paths within the same host as the
* site installation.
*
- * Do not use this method for URLs that do have a Drupal route (that is, most
- * pages generated by Drupal) because this will circumvent the routing system.
+ * Do not use this method for URLs that have a Drupal route (that is, most
+ * pages generated by Drupal). See the documentation of static::SCHEME_BASE
+ * for details.
*
* @param string $path
* The host-relative path. For example, if Drupal is installed in the
@@ -296,6 +332,7 @@
* A new Url object for an unrouted, host-relative URL not internal to
* Drupal, but relative to the site host.
*
+ * @see static::SCHEME_BASE
* @see static::fromBaseRelativePath()
* @see static::fromUri()
* @see static::fromRoute()