Improve API documentation

[bplotnick]

The API has gotten sufficiently complicated due to our insistence on not breaking backwards compatibility. This has made it pretty difficult to reason about the different method arguments and their effect. Eventually, we're going to need a refactor, but for now a documentation update will have to suffice.

We started to do this in the Other utilities section of the readme, but we should fill it out with things like client vs server root spans, include annotation filter, 128-bit trace-id, etc.