Issue #2700415 by nicolas.rafaelli, dimaro, rashid_786, er.pushpinderrana,...

Issue #2700415 by nicolas.rafaelli, dimaro, rashid_786, er.pushpinderrana, korgik, David Hernández, jhodgdon: Problems with documentation of options in Url class

core/lib/Drupal/Core/Url.php

@@ -55,6 +55,8 @@ class Url {
   /**
    * The URL options.
    *
+   * See \Drupal\Core\Url::fromUri() for details on the options.
+   *
    * @var array
    */
   protected $options = array();
@@ -101,21 +103,7 @@ class Url {
    * @param array $route_parameters
    *   (optional) An associative array of parameter names and values.
    * @param array $options
-   *   (optional) An associative array of additional options, with the following
-   *   elements:
-   *   - 'query': An array of query key/value-pairs (without any URL-encoding)
-   *     to append to the URL. Merged with the parameters array.
-   *   - 'fragment': A fragment identifier (named anchor) to append to the URL.
-   *     Do not include the leading '#' character.
-   *   - 'absolute': Defaults to FALSE. Whether to force the output to be an
-   *     absolute link (beginning with http:). Useful for links that will be
-   *     displayed outside the site, such as in an RSS feed.
-   *   - 'language': An optional language object used to look up the alias
-   *     for the URL. If $options['language'] is omitted, it defaults to the
-   *     current language for the language type LanguageInterface::TYPE_URL.
-   *   - 'https': Whether this URL should point to a secure location. If not
-   *     defined, the current scheme is used, so the user stays on HTTP or HTTPS
-   *     respectively. TRUE enforces HTTPS and FALSE enforces HTTP.
+   *   See \Drupal\Core\Url::fromUri() for details.
    *
    * @see static::fromRoute()
    * @see static::fromUri()
@@ -141,21 +129,7 @@ public function __construct($route_name, $route_parameters = array(), $options =
    * @param array $route_parameters
    *   (optional) An associative array of route parameter names and values.
    * @param array $options
-   *   (optional) An associative array of additional URL options, with the
-   *   following elements:
-   *   - 'query': An array of query key/value-pairs (without any URL-encoding)
-   *     to append to the URL. Merged with the parameters array.
-   *   - 'fragment': A fragment identifier (named anchor) to append to the URL.
-   *     Do not include the leading '#' character.
-   *   - 'absolute': Defaults to FALSE. Whether to force the output to be an
-   *     absolute link (beginning with http:). Useful for links that will be
-   *     displayed outside the site, such as in an RSS feed.
-   *   - 'language': An optional language object used to look up the alias
-   *     for the URL. If $options['language'] is omitted, it defaults to the
-   *     current language for the language type LanguageInterface::TYPE_URL.
-   *   - 'https': Whether this URL should point to a secure location. If not
-   *     defined, the current scheme is used, so the user stays on HTTP or HTTPS
-   *     respectively. TRUE enforces HTTPS and FALSE enforces HTTP.
+   *   See \Drupal\Core\Url::fromUri() for details.
    *
    * @return \Drupal\Core\Url
    *   A new Url object for a routed (internal to Drupal) URL.
@@ -265,6 +239,9 @@ public static function fromUserInput($user_input, $options = []) {
    *   - 'absolute': Defaults to FALSE. Whether to force the output to be an
    *     absolute link (beginning with http:). Useful for links that will be
    *     displayed outside the site, such as in an RSS feed.
+   *   - 'attributes': An associative array of HTML attributes that will be
+   *     added to the anchor tag if you use the \Drupal\Core\Link class to make
+   *     the link.
    *   - 'language': An optional language object used to look up the alias
    *     for the URL. If $options['language'] is omitted, it defaults to the
    *     current language for the language type LanguageInterface::TYPE_URL.
@@ -348,7 +325,7 @@ public static function fromUri($uri, $options = []) {
    *   Parts from an URI of the form entity:{entity_type}/{entity_id} as from
    *   parse_url().
    * @param array $options
-   *   An array of options, see static::fromUri() for details.
+   *   An array of options, see \Drupal\Core\Url::fromUri() for details.
    * @param string $uri
    *   The original entered URI.
    *
@@ -400,7 +377,7 @@ protected static function fromEntityUri(array $uri_parts, array $options, $uri)
    * @param array $uri_parts
    *   Parts from an URI of the form internal:{path} as from parse_url().
    * @param array $options
-   *   An array of options, see static::fromUri() for details.
+   *   An array of options, see \Drupal\Core\Url::fromUri() for details.
    *
    * @return \Drupal\Core\Url
    *   A new Url object for a 'internal:' URI.
@@ -447,7 +424,7 @@ protected static function fromInternalUri(array $uri_parts, array $options) {
    *   from parse_url(), where the path is the route name optionally followed by
    *   a ";" followed by route parameters in key=value format with & separators.
    * @param array $options
-   *   An array of options, see static::fromUri() for details.
+   *   An array of options, see \Drupal\Core\Url::fromUri() for details.
    * @param string $uri
    *   The original passed in URI.
    *
@@ -638,6 +615,8 @@ public function setRouteParameter($key, $value) {
    * Returns the URL options.
    *
    * @return array
+   *   The array of options. See \Drupal\Core\Url::fromUri() for details on what
+   *   it contains.
    */
   public function getOptions() {
     return $this->options;
@@ -646,6 +625,8 @@ public function getOptions() {
   /**
    * Gets a specific option.
    *
+   * See \Drupal\Core\Url::fromUri() for details on the options.
+   *
    * @param string $name
    *   The name of the option.
    *
@@ -664,7 +645,8 @@ public function getOption($name) {
    * Sets the URL options.
    *
    * @param array $options
-   *   The array of options.
+   *   The array of options. See \Drupal\Core\Url::fromUri() for details on what
+   *   it contains.
    *
    * @return $this
    */
@@ -676,6 +658,8 @@ public function setOptions($options) {
   /**
    * Sets a specific option.
    *
+   * See \Drupal\Core\Url::fromUri() for details on the options.
+   *
    * @param string $name
    *   The name of the option.
    * @param mixed $value