Make more explicit in which way an authenticator provider's priority is used to sort authenticator providers

AuthenticationManager says:

 * On each request, let all authentication providers try to authenticate the
 * user. The providers are iterated according to their priority and the first
 * provider detecting credentials for its method wins. No further provider will
 * get triggered.

and AuthenticationCollectorInterface says:

  /**
   * Returns the sorted array of authentication providers.
   *
   * @return \Drupal\Core\Authentication\AuthenticationProviderInterface[]
   *   An array of authentication provider objects.
   */
  public function getSortedProviders();

But in which order?

Symfony event listeners, which are also services with a priority, are run from high numbers to low numbers, as stated in the docs at https://symfony.com/doc/current/event_dispatcher.html:

> There is an optional attribute for the kernel.event_listener tag called priority, which is a positive or negative integer that defaults to 0 and it controls the order in which listeners are executed (the higher the number, the earlier a listener is executed).

So you might think it's the same here.

Or you might consider the way Drupal weights work, which is from low numbers to high numbers.

Looking at the code, I think that here it's high to low:

  public function addProvider(AuthenticationProviderInterface $provider, $provider_id, $priority = 0, $global = FALSE) {
    $this->providers[$provider_id] = $provider;
    $this->providerOrders[$priority][$provider_id] = $provider;

SNIP

  public function getSortedProviders() {
    if (!isset($this->sortedProviders)) {
      // Sort the providers according to priority.
      krsort($this->providerOrders);

but the only difference between the two is the 'r' in 'krsort' vs 'ksort' and honestly I was about to write here that it's low to high because I misread it the first time!

This needs to be documented:

- in AuthenticationCollectorInterface, because otherwise an implementation of this interface could get it wrong
- in AuthenticationManager so developers creating an authentication provider understand how to set the priority value