Improve documentation of MenuLinkTreeInterface

Problem/Motivation

MenuLinkTreeInterface::load() does not do any sorting or access checks, as might be expected. This should be better documented.

When loading a menu, for example using:

$tree = \Drupal::menuTree()->load('menu', new MenuTreeParameters());

the subtrees is not necessarily sorted by weight. For the subtrees to be sorted by weight we need to do something like:

$tree = \Drupal::menuTree()->load('menu', new MenuTreeParameters());

foreach ($tree as $key => $item) {
  usort($tree[$key]['subtree'], function($a, $b) {
    if ($a->link->getWeight() == $b->link->getWeight()) {
      return 0;
    }
    return ($a->link->getWeight() < $b->link->getWeight()) ? -1 : 1;
  });
}

This is unwieldy for developers, and the problem is compounded by the fact that the subtree _can_ be sorted, but is not necessarily, so if a subtree is sorted during development, it is easy to overlook this requirement.

Proposed resolution

Improve documentation.

Remaining tasks

Finalize documentation improvement.

User interface changes

None.

Introduced terminology

None.

API changes

None.

Data model changes

None.

Release notes snippet