Cover span handof scenarios in a bit more detail

[rbtcollins]

This came up because I had to ask in gitter.im about the details here, so I thought I'd capture it for everyone.

[coveralls]

Coverage remained the same at 73.09% when pulling 9c94df0 on rbtcollins:patch-1 into e000eb0 on opentracing:master.

[yurishkuro]

@rbtcollins note that continuations are most likely going away in 0.31

[rbtcollins]

@yurishkuro sure, but doing both of these things has to remain possible right? So the merge of the Scopes or whatever should have the same, but updated docs in it. What do you think of the docs? Are they accurate? Can has merge? :)

[yurishkuro]

I think my point is that in 0.31 the Continuation is going away because it was demonstrated that most async scenarios can be handled without continuations and ref counting. The Scope in 0.31 is functionally equivalent to ActiveSpan in 0.30. That's why I questioned the value of writing examples that still utilize continuations rather than writing them using ActiveSpan only.

[rbtcollins]

Well, its not clear to me yet how we'll integrate that in in Xenon. We just merged 0.30.0 instrumentation, and when I went looking at the 0.31 branch there was no updated user docs; so I figured updating the current docs was reasonable to cover this use case, and then when the 0.31 docs are updated, whoever is doing that can update this as well.

[tedsuo]

@rbtcollins I'm sure we'll do more copy editing, but the docs are updated: https://github.com/opentracing/opentracing-java/tree/v0.31.0

[carlosalberto]

Hey @rbtcollins

Sorry for the long delayed ping. Wondering if we should discard these changes, now that we don't use Continuations as part of the main API (we still have AutoFinishScopeManager, but that is part of opentracing-util and does extra things not covered by it ;) )

Let us know.