Document https://github.com/kataras/iris/issues/720 and fix https://github.com/kataras/iris/issues/719 for good

Former-commit-id: 75b855bee9216c28ce8e1ff46aee467766c37f23

context/context.go

@@ -758,6 +758,19 @@ func Next(ctx Context) {
 	}
 }
 
+// Do calls the SetHandlers(handlers)
+// and executes the first handler,
+// handlers should not be empty.
+//
+// It's used by the router, developers may use that
+// to replace and execute handlers immediately.
+func Do(ctx Context, handlers Handlers) {
+	if len(handlers) > 0 {
+		ctx.SetHandlers(handlers)
+		handlers[0](ctx)
+	}
+}
+
 // LimitRequestBodySize is a middleware which sets a request body size limit
 // for all next handlers in the chain.
 var LimitRequestBodySize = func(maxRequestBodySizeBytes int64) Handler {

context/pool.go

@@ -21,6 +21,11 @@ func New(newFunc func() Context) *Pool {
 }
 
 // Attach changes the pool's return value Context.
+//
+// The new Context should explicitly define the `Next()`
+// and `Do(context.Handlers)` functions.
+//
+// Example: https://github.com/kataras/iris/blob/master/_examples/routing/custom-context/method-overriding/main.go
 func (c *Pool) Attach(newFunc func() Context) {
 	c.newFunc = newFunc
 }