Editing pass over godocs in the root package.

I'm fleshing out the existing documentation and explicitly marking things as being used internally, deprecated, and so on. I've also expanded the package-global introduction that @jamiehannaford wrote to include a few more expected usage patterns.

In general, I'm trying to give all of the documentation a sturdier sense of how things are related, how things are used, and where someone should look next.
s/used to by/used by