Issue #3015631 by liam morland, smustgrave, alberto56, amateescu, batkor:...

Issue #3015631 by liam morland, smustgrave, alberto56, amateescu, batkor: Improve documentation of MenuLinkTreeInterface

core/lib/Drupal/Core/Menu/MenuLinkTreeInterface.php

@@ -50,6 +50,8 @@ public function getCurrentRouteMenuTreeParameters($menu_name);
   /**
    * Loads a menu tree with a menu link plugin instance at each element.
    *
+   * There will be no sorting or access checks. For that, use ::transform().
+   *
    * @param string $menu_name
    *   The name of the menu.
    * @param \Drupal\Core\Menu\MenuTreeParameters $parameters
@@ -70,6 +72,14 @@ public function load($menu_name, MenuTreeParameters $parameters);
    *   - callable: a callable or a string that can be resolved to a callable
    *     by Drupal\Core\Utility\CallableResolver::getCallableFromDefinition()
    *   - args: optional array of arguments to pass to the callable after $tree.
+   *   For example, to sort and check access:
+   *   @code
+   *   $manipulators = [
+   *     ['callable' => 'menu.default_tree_manipulators:checkNodeAccess'],
+   *     ['callable' => 'menu.default_tree_manipulators:checkAccess'],
+   *     ['callable' => 'menu.default_tree_manipulators:generateIndexAndSort'],
+   *   ];
+   *   @endcode
    *
    * @return \Drupal\Core\Menu\MenuLinkTreeElement[]
    *   The manipulated menu link tree.