Enhanced documentation for each package

[peterbourgon]

• Investigate using davecheney/godoc2md to produce READMEs for each package, including only the package summaries, not the full API. This may require adapting the tool.
• Finish the rationale sections.
• Add proper example functions to illustrate usage, rather than excerpts in the READMEs.

[harlow]

@peterbourgon do you think its worth creating an example README by hand first? Something we can all agree on and then seeing how we can use computers to re-generate it?

I like the idea of having examples that are verified by the test suite. This should help reduce the chances of README drift.

[peterbourgon]

I'd rather tackle it from the other angle: see what the tools can do, and then tweak it as necessary. I honestly don't care about many of the details, as long as we have a package overview, a rationale, and links to the example_xxx.go examples.

[peterbourgon]

I've pushed an overhaul to the documentation, focusing heavily on examples. Still some rough edges to smooth out, e.g. #107, but this can be considered done, I think.