We have several somewhat overlapping places where various bits of the menu/routing system are documented:
We need three kinds of documentation:
- Change records to document the before-and-after for
hook_menu()and its ilk from D7 to D8. Already partially done in the appropriate issues, but exists to cover the gaps.
- API documentation in the codebase for how routes are declared, especially for Drupalisms like our various route parameters. Slightly trickier because these are not something we can just stick a docblock on like we can a function, class, or class member. See https://api.drupal.org/api/drupal/core!includes!menu.inc/group/menu/8. . This should take the form of an overhaul of the routing and menu group as shown in
- A comprehensive overview in the handbook that explains not only the API itself but how to develop with it. We have a good start at this already at https://drupal.org/developing/api/8/routing and in its sub-pages, but there's a lot more to be filled in.
Original report by chx
Ifis a go then it is now critical to document the router. There is zero documentation as far as I am concerned, the rough overview over at Symfony is inadequate even for them and doesn't cover Drupal at all. We need flowcharts, internals (so that one can debug it), explanations (why do we use _controller / _form instead of just form? etc) and examples.
For posterity, the documentation or some semblance of it now can be found at https://drupal.org/node/2122071 . It didn't even take a year to get some documentation up. And that, of course, was not written by anyone in the WSCCI team because they are exempt from such small details like producing developer friendly, performant, documented code.