Improve documentation around explicit routing

Fixes #120.

web/middleware/subrouter.go

@@ -42,18 +42,24 @@ func (s subrouter) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	s.h.ServeHTTP(w, r)
 }
 
-// SubRouter is a helper middleware that makes writing sub-routers easier.
-//
-// If you register a sub-router under a key like "/admin/*", Goji's router will
-// automatically set c.URLParams["*"] to the unmatched path suffix. This
-// middleware will help you set the request URL's Path to this unmatched suffix,
-// allowing you to write sub-routers with no knowledge of what routes the parent
-// router matches.
-//
-// Since Go's regular expressions do not allow you to create a capturing group
-// named "*", SubRouter also accepts the string "_". For instance, to duplicate
-// the semantics of the string pattern "/foo/*", you might use the regular
-// expression "^/foo(?P<_>/.*)$".
+/*
+SubRouter is a helper middleware that makes writing sub-routers easier.
+
+If you register a sub-router under a key like "/admin/*", Goji's router will
+automatically set c.URLParams["*"] to the unmatched path suffix. This middleware
+will help you set the request URL's Path to this unmatched suffix, allowing you
+to write sub-routers with no knowledge of what routes the parent router matches.
+
+Since Go's regular expressions do not allow you to create a capturing group
+named "*", SubRouter also accepts the string "_". For instance, to duplicate the
+semantics of the string pattern "/foo/*", you might use the regular expression
+"^/foo(?P<_>/.*)$".
+
+This middleware is Match-aware: it will un-set any explicit routing information
+contained in the Goji context in order to prevent routing loops when using
+explicit routing with sub-routers. See the documentation for Mux.Router for
+more.
+*/
 func SubRouter(c *web.C, h http.Handler) http.Handler {
 	return subrouter{c, h}
 }

web/mux.go

@@ -101,13 +101,21 @@ func (rm routerMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	rm.h.ServeHTTP(w, r)
 }
 
-// Router is a middleware that performs routing and stores the resulting Match
-// in Goji's environment. If a routing Match is present at the end of the
-// middleware stack, that Match is used instead of re-routing.
-//
-// This middleware is especially useful to create post-routing middleware, e.g.
-// a request logger which prints which pattern or handler was selected, or an
-// authentication middleware which only applies to certain routes.
+/*
+Router is a middleware that performs routing and stores the resulting Match in
+Goji's environment. If a routing Match is present at the end of the middleware
+stack, that Match is used instead of re-routing.
+
+This middleware is especially useful to create post-routing middleware, e.g. a
+request logger which prints which pattern or handler was selected, or an
+authentication middleware which only applies to certain routes.
+
+If you use nested Muxes with explicit routing, you should be aware that the
+explicit routing information set by an outer Mux can be picked up by an inner
+Mux, inadvertently causing an infinite routing loop. If you use both explicit
+routing and nested Muxes, you should be sure to unset MatchKey before the inner
+Mux performs routing (or attach a Router to the inner Mux as well).
+*/
 func (m *Mux) Router(c *C, h http.Handler) http.Handler {
 	return routerMiddleware{m, c, h}
 }