diff --git a/core/lib/Drupal/Component/Utility/UrlHelper.php b/core/lib/Drupal/Component/Utility/UrlHelper.php
index a216f21..52b746f 100644
--- a/core/lib/Drupal/Component/Utility/UrlHelper.php
+++ b/core/lib/Drupal/Component/Utility/UrlHelper.php
@@ -112,30 +112,30 @@ public static function filterQueryParameters(array $query, array $exclude = arra
   }
 
   /**
-   * Parses a system URL string into an associative array.
+   * Parses a URL string into its path, query, and fragment components.
    *
-   * This function should only be used for URLs that have been generated by the
-   * system. It should not be used for URLs that come from external sources, or
-   * URLs that link to external resources.
+   * This function splits both internal paths like @code node?b=c#d @endcode and
+   * external URLs like @code https://example.com/a?b=c#d @endcode into their
+   * component parts. See
+   * @link http://tools.ietf.org/html/rfc3986#section-3 RFC 3986 @endlink for an
+   * explanation of what the component parts are.
    *
-   * The returned array contains a 'path' that may be passed separately to url().
-   * For example:
-   * @code
-   *   $options = UrlHelper::parse(\Drupal::request()->query->get('destination'));
-   *   $my_url = url($options['path'], $options);
-   *   $my_link = l('Example link', $options['path'], $options);
-   * @endcode
+   * Note, however, that when passed an external URL, this function groups the
+   * scheme, authority and path together into the path component.
    *
    * @param string $url
-   *   The URL string to parse, i.e.
-   *     \Drupal::request()->query->get('destination').
+   *   The internal path or external URL string to parse.
    *
-   * @return
-   *   An associative array containing the keys:
-   *   - 'path': The path of the URL. If the given $url is external, this includes
-   *     the scheme and host.
-   *   - 'query': An array of query parameters of $url, if existent.
-   *   - 'fragment': The fragment of $url, if existent.
+   * @return array
+   *   An associative array containing:
+   *   - path: The path component of $url. If $url is an external URL, this
+   *     includes the scheme and host.
+   *   - query: An array of query parameters from $url, if they exist.
+   *   - fragment: The fragment component from $url, if it exists.
+   *
+   * @see l()
+   * @see \Drupal::url()
+   * @see http://tools.ietf.org/html/rfc3986
    *
    * @ingroup php_wrappers
    */