Document about menu ordering

Working on it.

The dead link discussed various database strategies for storing hierarchical data, such as:

• Materialized path (e.g., storing a path like /1/4/7)
• Nested set model
• Adjacency list
• Closure table

While this was relevant in older versions of Drupal (e.g., 6/7), in modern Drupal (8+), menu trees are abstracted through MenuTreeStorageInterface and implemented by MenuTreeStorage. Internally, a materialized path-like structure is still used (e.g., storing parent, depth, and weight), but this is implementation-specific and subject to change — as the doc comment rightly warns.

Where should this documentation live?

I see two good options:

1- In-code documentation, e.g.:
A @defgroup menu_tree_storage block in menu.api.php
Or an @ingroup docblock in MenuTreeStorageInterface or MenuTreeStorage
This would describe the storage strategies, how ordering is applied, and what’s considered internal/subject to change

2- Drupal.org handbook or developer documentation:
A dedicated page under Menus or API > System > Menu System
More detailed and user-friendly, good for those exploring how menu links are built and ordered

Thanks,
Arun

Not sure NR is the correct status.

@smustgrave could you please guide me with best approach here.