Fix many Buffer bugs, add tests and a ton of docs.

This commit whips Buffer into shape. At this point, I think the
type is well-documented enough that people can probably use it
without it accidentally blowing their feet off.

The type does have caveats, which I tried to include in the docs.
But at this point I'm reasonably sure that it work. At least, we
have pretty decent test coverage now.