Clarify possible contents of each link array on theme_links/links.html.twig

Problem/Motivation

The theme_links documentation ( https://api.drupal.org/api/drupal/includes%21theme.inc/function/theme_li... ) about the possible contents of each link array inside the links array can be confusing. The documentation says it can only receive four parameters (href, title, html and attributes). Later, also says that, if href is present, it will be passed to the l() function as the $options value. But it doesn't say that this $options will be passed to the url() function, that can receive a lot more different values.

Here is an example of how this documentation can be confusing:

If you want to create a list of links like <a href="#">Title</a> (to be used for ajax calls, for example), using the l function will be like this:

l('Title', '', array('fragment' => FALSE, 'external' => TRUE));

Using the theme_links function, the $link array should be like this:

$link = array(
  'href' => '',
  'title' => 'Title',
  'fragment' => FALSE,
  'external' => TRUE,
);

But reading the documentation I expected to be something like this:

$link = array(
  'href' => '',
  'title' => 'Title',
  'attributes' => array(
    'fragment' => FALSE,
    'external' => TRUE,
  ),
);

Proposed resolution

Add some text to specify that, when the href is present and the $link is passed to the l() function, it will also call the url() function, increasing the number of parameters that can receive.

Remaining tasks

Review propossed patch.

User interface changes

None

API changes

None