Use native GoDoc examples

This replaces the enormous free-form docstring at the top with something
that's at least syntax highlighted and collapsible. I'm a little worried
about discoverability, but "oh well."

web/example_test.go

@@ -0,0 +1,69 @@
+package web_test
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	"regexp"
+
+	"github.com/zenazn/goji/web"
+	"github.com/zenazn/goji/web/middleware"
+)
+
+func Example() {
+	m := web.New()
+
+	// Use your favorite HTTP verbs and the interfaces you know and love
+	// from net/http:
+	m.Get("/hello", func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintf(w, "Why hello there!\n")
+	})
+	m.Post("/login", func(w http.ResponseWriter, r *http.Request) {
+		if r.FormValue("password") != "god" {
+			http.Error(w, "Hack the planet!", 401)
+		}
+	})
+
+	// Handlers can optionally take a context parameter, which contains
+	// (among other things) a set of bound parameters.
+	hello := func(c web.C, w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintf(w, "Hello, %s!\n", c.URLParams["name"])
+	}
+
+	// Bind parameters using pattern strings...
+	m.Get("/hello/:name", hello)
+
+	// ...or use regular expressions if you need additional power.
+	bonjour := regexp.MustCompile(`^/bonjour/(?P<name>[A-Za-z]+)$`)
+	m.Get(bonjour, hello)
+
+	// Middleware are a great abstraction for performing logic on every
+	// request. Some middleware use the Goji context object to set
+	// request-scoped variables.
+	logger := func(h http.Handler) http.Handler {
+		wrap := func(w http.ResponseWriter, r *http.Request) {
+			log.Println("Before request")
+			h.ServeHTTP(w, r)
+			log.Println("After request")
+		}
+		return http.HandlerFunc(wrap)
+	}
+	auth := func(c *web.C, h http.Handler) http.Handler {
+		wrap := func(w http.ResponseWriter, r *http.Request) {
+			if cookie, err := r.Cookie("user"); err == nil {
+				c.Env["user"] = cookie.Value
+			}
+			h.ServeHTTP(w, r)
+		}
+		return http.HandlerFunc(wrap)
+	}
+
+	// A Middleware stack is a flexible way to assemble the common
+	// components of your application, like request loggers and
+	// authentication. There is an ecosystem of open-source middleware for
+	// Goji, so there's a chance someone has already written the middleware
+	// you are looking for!
+	m.Use(middleware.EnvInit)
+	m.Use(logger)
+	m.Use(auth)
+}

web/web.go

@@ -7,65 +7,6 @@ and regular expressions. Second, it allows you to write reconfigurable
 middleware stacks. And finally, it allows you to attach additional context to
 requests, in a manner that can be manipulated by both compliant middleware and
 handlers.
-
-A usage example:
-
-	m := web.New()
-
-Use your favorite HTTP verbs and the interfaces you know and love from net/http:
-
-	var existingHTTPHandler http.Handler // From elsewhere
-	m.Get("/foo", existingHTTPHandler)
-	m.Post("/bar", func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte("Hello world!"))
-	})
-
-Bind parameters using either named captures or regular expressions:
-
-	m.Get("/hello/:name", func(c web.C, w http.ResponseWriter, r *http.Request) {
-		fmt.Fprintf(w, "Hello, %s!", c.URLParams["name"])
-	})
-	pattern := regexp.MustCompile(`^/ip/(?P<ip>(?:\d{1,3}\.){3}\d{1,3})$`)
-	m.Get(pattern, func(c web.C, w http.ResponseWriter, r *http.Request) {
-		fmt.Fprintf(w, "Info for IP address %s:", c.URLParams["ip"])
-	})
-
-Middleware are functions that wrap http.Handlers, just like you'd use with raw
-net/http. Middleware functions can optionally take a context parameter, which
-will be threaded throughout the middleware stack and to the final handler, even
-if not all of the intervening middleware or handlers support contexts.
-Middleware are encouraged to use the Env parameter to pass request-scoped data
-to other middleware and to the final handler:
-
-	func LoggerMiddleware(h http.Handler) http.Handler {
-		handler := func(w http.ResponseWriter, r *http.Request) {
-			log.Println("Before request")
-			h.ServeHTTP(w, r)
-			log.Println("After request")
-		}
-		return http.HandlerFunc(handler)
-	}
-	func AuthMiddleware(c *web.C, h http.Handler) http.Handler {
-		handler := func(w http.ResponseWriter, r *http.Request) {
-			if cookie, err := r.Cookie("user"); err == nil {
-				c.Env["user"] = cookie.Value
-			}
-			h.ServeHTTP(w, r)
-		}
-		return http.HandlerFunc(handler)
-	}
-
-	// This makes the AuthMiddleware above a little cleaner
-	m.Use(middleware.EnvInit)
-	m.Use(AuthMiddleware)
-	m.Use(LoggerMiddleware)
-	m.Get("/baz", func(c web.C, w http.ResponseWriter, r *http.Request) {
-		if user, ok := c.Env["user"].(string); ok {
-			w.Write([]byte("Hello " + user))
-		} else {
-			w.Write([]byte("Hello Stranger!"))
-		}
-	})
 */
 package web