RouteBuilderInterface has no docblock

+++ b/core/lib/Drupal/Core/Routing/RouteBuilderInterface.php
@@ -7,6 +7,11 @@
+/**
+ * Builds and possibly dumps the route information.
+ *
+ * @ingroup menu
+ */

What about adding a @see to the Route provider and MatcherDumperInterface

I like the @ingroup menu but the RouteBuilder <-> RouterProvider are sort of always together, they support each other.

Routes are deliberately not part of the menu system anymore, so I don't think @ingroup menu is correct. Do we have a routing @group? If not, we should. :-)

The dumper and matcher come as a matched set, but the RouteBuilder itself shouldn't need to be swapped out for a new matcher/dumper set (eg, a Mongo or Cassandra backend).

I would suggest a description here of just "Rebuilds compiled routing information", with an @ingroup of "routing".

Thanks chx for the catch.

Can you somehow have nested groups?

Well, then let's start with @ingroup menu, its the right thing to do now.

Then we should start a new @group for routing specifically. Whether we do that as part of this patch or file a follow-up to reorganize it in the next patch, I defer to the committers on. As long as the follow-up is actually filed I am OK either way.

We can now revive this... On another issue, Menu and Routing topics were split up. See
https://api.drupal.org/api/drupal/8

Use @ingroup routing now instead of @ingroup menu, which will add it to the new split Routing topic:

https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Routing!routing.a...

OK. What we need is for someone to take the patch from above and change @ingroup menu to @ingroup routing. Good Novice task...

Updating issue summary to match the patch/title.

Maybe an @see to MatcherDumperInterface and RouteProviderInterface could be helpful.

Sounds like a good idea. Note that in docs headers, when referring to a class include the full namespace.

Little busy, Anyone else can pick up.

Added @see to MatcherDumperInterface and RouteProviderInterface.

Reexported patch

OK, let's do it.

+++ b/core/lib/Drupal/Core/Routing/RouteBuilderInterface.php
@@ -7,6 +7,14 @@
+ * Builds and possibly dumps the route information.

Rebuilds the route info and dumps to dumper. is the documentation on the rebuild method - does that need adjusting too? Also I'd have thought some description about what building routes means would be appropriate - or pointing to some documentation that does this.

Attaching patch as no activity for a longer time.

Hm. Neither of those interfaces gives me any indication of what "rebuilding" or "dumping" means, actually. So I think this needs some more work.

Can you give hint what should be there.

I really don't know what this interface, or the classes that implement it do. But the doc block in this patch just says:

+/*
+ * Rebuilds the route info and dumps to dumper.
+ *
+ * @see \Drupal\Core\Routing\MatcherDumperInterface
+ * @see \Drupal\Core\Routing\RouteProviderInterface
+ *
+ * @ingroup routing
+ */
 interface RouteBuilderInterface {

So it just says it "rebuilds" the route info and "dumps" it to the Dumper. I kind of know what "rebuilds" means, but it would help if the interface told me that. I don't know at all what "dumps" means, so it would be very helpful if it told me what that was.

All I have, instead, is two @see references. If I look at the docs for these two interfaces, all the extremely non-helpful information I get is:

a)

Extends the symfony matcher dumper interface with a addRoutes method.

b)

Extends the router provider interface

This tells me absolutely nothing about what "rebuilding" or "dumping" is. Not helpful at all. So... this either needs to link me to some docs that explain what these two terms are, or explain them. And since I personally do not know what they mean exactly, sorry, I cannot help you... but those two interfaces are extensions of Symfony interfaces, and although Symfony has nearly zero API docs in their docs header, they do have quite a bit on their project site, so you might be able to learn more there or find a link that could be put into an @see, something like:

@see http://symfony.com/whatever/whatever/whatever

or better yet, a paragraph something like:

See http://symfony.com/something and http://symfony.com/something_else for more information on the route rebuilding and dumping process.

Thanks! This looks really excellent.

Except for one line:

+++ b/core/lib/Drupal/Core/Routing/RouteBuilderInterface.php
@@ -13,7 +30,7 @@
+   * Rebuilds the route information and dumps it, but only if necessary.

In your comment that came with the patch, you said that the "only if necessary" phrase applied to the rebuild. So, this line still seems wrong/ambiguous? Maybe it should say "Rebuilds the route information if necessary, and dumps it."?

Looks good to me. Thanks for the research and patches!

Committed 57a5e9a and pushed to 8.1.x and 8.2.x. Thanks!

Yeah!