docs(group): explain how group catch-all NotFound routes replace RouteNotFound handlers (#3155)

When a group has middlewares, `Group#Use()` registers catch-all NotFound routes for the group prefix and prefix + `/*` so the middlewares also run for unmatched paths. This is by design (#2411), but the `Group.RouteNotFound` doc did not say so.

The note documents which calls register these routes, that the last registered NotFound route for a path wins with only the group middlewares it was registered with, where to register custom handlers, and what to do on routers that do not allow overwriting routes.

Refs #3153

Author: vishr

group.go

@@ -183,6 +183,17 @@ func (g *Group) File(path, file string, middleware ...MiddlewareFunc) RouteInfo
 
 // RouteNotFound implements `Echo#RouteNotFound()` for sub-routes within the Group.
 //
+// Important! When the group has middlewares, each `Group#Use()` call (re)registers catch-all NotFound routes for
+// the group prefix and prefix + `/*` with the group middlewares, unless the Echo-wide
+// `Config.NoGroupAutoRegister404Routes` is set. `Echo#Group()` and `Group#Group()` make this call when the new group
+// has own or inherited middlewares. For the same route path the last registered NotFound route wins, and it runs
+// only the group middlewares it was registered with: these catch-all routes replace handlers registered earlier for
+// those paths (by any group or by Echo), and a handler registered later replaces them. Register custom ones on this
+// group after the last such call for its prefix to keep its middlewares. On a Router that does not allow overwriting
+// routes this panics; use the router-wide `RouterConfig.NotFoundHandler` there, or set
+// `Config.NoGroupAutoRegister404Routes` and register both paths yourself on the group whose middlewares should run
+// for them.
+//
 // Example: `g.RouteNotFound("/*", func(c *echo.Context) error { return c.NoContent(http.StatusNotFound) })`
 func (g *Group) RouteNotFound(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo {
 	return g.Add(RouteNotFound, path, h, m...)