In order to expose a convenient API, it's unfortunately necessary to
lean on Go's interface{} quite a bit: in reality we only accept a
handful of types at each call site, but it's impossible to express this
using the type system.
Prior to this commit (as well as the ParsePattern commit), I exposed all
of this type information in the form of an enormous comment on web.Mux,
however this was pretty gross. Instead, let's use "vanity" type aliases
for interface{} to provide documentation about which types are accepted
where. This will hopefully make the API documentation easier to skim,
but doesn't affect any existing uses of Goji.
This commit also clarifies a couple other parts of the documentation.
The "name" parameter was originally a workaround for the fact that function
pointers in Go never compare equal to each other (unless they are both nil).
Unfortunately, this presents a pretty terrible interface to the end programmer,
since they'll probably end up stuttering something like:
mux.Use("MyMiddleware", MyMiddleware)
Luckily, I found a workaround for doing function pointer equality (it doesn't
even require "unsafe"!), so we can get rid of the name parameter for good.
This change replaces a bit of API surface area (the Sub() method on Muxes) with
a slightly more expressive pattern syntax. I'm mostly doing this because it
seems cleaner: the "*" gets to take on a meaning very similar to what it means
in Sinatra (without growing regexp-like middle-of-a-path globbing, which sounds
terrifying and not particularly useful), and we get to nuke a useless function
from the API.
Carl Jackson
Coda Hale