diff --git a/core/lib/Drupal.php b/core/lib/Drupal.php
index b355847..2f78f7a 100644
--- a/core/lib/Drupal.php
+++ b/core/lib/Drupal.php
@@ -501,6 +501,19 @@ public static function urlGenerator() {
    *   does not match the requirement.
    *
    * @see \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute()
+   *
+ * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.0.
+ *   Use \Drupal\Core\Url::fromRoute() for internal paths served by Drupal
+ *   controllers or \Drupal\Core\Url::fromUri() for external paths or
+ *   non-controller or sub-domain URIs such as core/install.php. Note that
+ *   \Drupal\Core\Url::fromUri() expects a valid URI including the scheme. URIs
+ *   from the same sub-domain that are not handled by Drupal controllers should
+ *   be prepended with base://. For example:
+ * @code
+ * $installer_url = \Drupal\Core\Url::fromUri('base://core/install.php')->toString();
+ * $external_url = \Drupal\Core\Url::fromUri('http://example.com', ['query' => ['foo' => 'bar']])->toString();
+ * $internal_url = \Drupal\Core\Url::fromRoute('system.admin')->toString();
+ * @endcode
    */
   public static function url($route_name, $route_parameters = array(), $options = array()) {
     return static::$container->get('url_generator')->generateFromRoute($route_name, $route_parameters, $options);