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.
I actually just added it. I thought we should have *something* that was directly relevant to the contents of the package we were commenting on :grin: Saying "you probably don't actually care about anything that's right here, except for these two things" is probably better than bewildering anyone who scrolls down and tries to relate the contents to the architecture we're describing in the rest.