Docs reference outdated API

[AdrianSchneble]

The "Scopes" doc references Tracer.SpanBuilder.startActiveSpan(boolean finishOnClose), which does not match the latest version of OpenTracing.

As far as I can tell, the default is now simply that every span is set as active when .started. Regardless, the docs should be changed to reflect the latest version.

This is not the only issue with the docs, there are also numerous other examples of outdated example code (in the "Scopes" doc or other sections of the docs).

I'm aware that OpenTracing is merging with OpenCensus into OpenTelemetry, but I don't think that's an "excuse" for incorrect documentation (insofar as voluntary contributors have to make "excuses").

[whiskeysierra]

As far as I can tell, the default is now simply that every span is set as active when .started.

That is not correct. The pattern is that span lifecycle (start/finish) is now properly separated from scope lifecycle (activate/close).

[MxKaras]

Given the changes, I'm trying to think under what conditions one would want to manage a scope's lifecycle. Is there any need to pay attention to it now?

[whiskeysierra]

Scopes are optional and users should be very interested in controlling the timeframe in which a span is active. It's not something that anyone should ignore.