try-with-resources (which doesn't work) is still the main documented way to use OpenTracing in java

[dhalperi]

cc: @felixbarny @carlosalberto (after #301, related #361)

"finishSpanOnClose" in "try-with-resources" is still the main documented way of using spans. E.g., see: https://opentracing.io/guides/java/scopes/#scope-objects which recommends

Tracer.SpanBuilder.startActiveSpan(boolean finishOnClose) will create a new Span and will automatically set is as the active one for the current context.

import io.opentracing.Scope;

// Strongly encouraged to use them under try statements,
// to prevent ending up with the incorrect active Span
// in case of error.
try (Scope scope = tracer.buildSpan("foo").startActive(true)) {
    scope.span().setTag(...);
    scope.span().log(...);
}

  // The 'foo' Span is finished at this point.

And there are several dead javadoc links throughout the codebase to startActive(boolean), which has been removed. https://github.com/opentracing/opentracing-java/blob/master/opentracing-api/src/main/java/io/opentracing/Tracer.java#L166