Make HTTP middleware easier to use

server/router/doc.go

Index: server/router/doc.go
diff --git a/server/router/doc.go b/server/router/doc.go
new file mode 100644
index 0000000000000000000000000000000000000000..e6be0012f374e52d6b7e03a44afa9f6d5aa3122c
--- /dev/null
+++ b/server/router/doc.go
@@ -0,0 +1,31 @@
+// Copyright 2016 The LUCI Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package router provides an HTTP router with support for middleware and groups.
+// It wraps around julienschmidt/httprouter.
+//
+// Usage:
+//
+//  	r := router.New()
+//  	r.Use(MiddlewareChain{Logger()})
+//  	r.GET("/", MiddlewareChain{Foo()}, rootHandler) // Executes Logger, Foo, rootHandler in order
+//
+//  	authorized := r.Group("authorized")
+//  	authorized.Use(MiddlewareChain{Authenticator(), Bar()})
+//  	authorized.DELETE("/comment/:id", nil, delHandler) // Executes Logger, Authenticator, Bar, delHandler in order (path: /authorized/comment/:id)
+//
+//  	func rootHandler(c *router.Context) {
+//  		io.WriteString(c, "hello from the root route")
+//  	}
+//
+//  	func Logger() router.Middleware {
+//  		return func(c *router.Context, next router.Handler) {
+//  			print("log before")
+//  			c.Context = context.WithValue(c.Context, "x", "y")
+//  			next(c)
+//  			print("log after")
+//  		}
+//  	}
+//

[nodir, 2016/06/15 20:14:43]

it may be (or may be not) better to move this example to example_test.go, see
"Larger examples" section in https://blog.golang.org/examples

this way we will be sure it compiles and it may be nicely formatted on godoc

[nishanths, 2016/06/16 00:14:18]

Moved to example_test.go and removed this file. Compilation checking huge plus.
:)

+package router