Updates in README and code comments as per reviewer's request

Signed-off-by: Oleksandr Bukaiev <[email protected]>

README.md

@@ -108,12 +108,19 @@ JAEGER_SAMPLING_ENDPOINT | The url for the remote sampling conf when using sampl
 JAEGER_TAGS | A comma separated list of `name = value` tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format `${envVarName:default}`, where the `:default` is optional, and identifies a value to be used if the environment variable cannot be found
 
 ### SelfRef
-Jaeger Tracer supports an additional reference type call 'SelfRef'. This allows a caller to provide traceId and spanId for the root span.
-Must be the lone reference.
-Usage example:
-  jaegertracing::SpanContext spanContextWithUserIDs { {1, 2}, 3, 0, 0, jaegertracing::SpanContext::StrMap() }; // TraceId and SpanID must be != 0
-  auto span = opentracing::Tracer::Global()->StartSpan("tracedFunction1", {jaegertracing::SelfRef(&spanContextWithUserIDs)});
+Jaeger Tracer supports an additional reference type call 'SelfRef'.
+It returns an opentracing::SpanReference which can be passed to Tracer::StartSpan
+to influence the SpanContext of the newly created span. Specifically, the new span inherits the traceID
+and spanID from the passed SELF reference. It can be used to pass externally generated IDs to the tracer,
+with the purpose of recording spans from data generated elsewhere (e.g. from logs), or by augmenting the
+data of the existing span (Jaeger backend will merge multiple instances of the spans with the same IDs).
+Must be the lone reference, can be used only for root spans.
 
+Usage example:
+```
+  jaegertracing::SpanContext customCtx { {1, 2}, 3, 0, 0, jaegertracing::SpanContext::StrMap() }; // TraceId and SpanID must be != 0
+  auto span = tracer->StartSpan("spanName", { jaegertracing::SelfRef(&customCtx) });
+```
 
 ## License
 

src/jaegertracing/Tracer.cpp

@@ -33,8 +33,7 @@ using SystemClock = Tracer::SystemClock;
 using SteadyClock = Tracer::SteadyClock;
 using TimePoints = std::tuple<SystemClock::time_point, SteadyClock::time_point>;
 
-// An extension of enum opentracing::SpanReferenceType, for a new Span. Only to copy traceID and (for non-root spans) spanID
-// spanID for root spans still traceID.low()
+// An extension of opentracing::SpanReferenceType enum. See jaegertracing::SelfRef().
 const static int SpanReferenceType_JaegerSpecific_SelfRef = 99;
 
 TimePoints determineStartTimes(const opentracing::StartSpanOptions& options)

src/jaegertracing/Tracer.h

@@ -304,9 +304,12 @@ class Tracer : public opentracing::Tracer,
 };
 
 
-// jaegertracing::SelfRef returns a StartSpanOption pointing to the Span which traceID and spanID should become the new Span's IDs
-//
-// See opentracing::SpanReference
+// jaegertracing::SelfRef() returns an opentracing::SpanReference which can be passed to Tracer::StartSpan
+// to influence the SpanContext of the newly created span. Specifically, the new span inherits the traceID
+// and spanID from the passed SELF reference. It can be used to pass externally generated IDs to the tracer,
+// with the purpose of recording spans from data generated elsewhere (e.g. from logs), or by augmenting the
+// data of the existing span (Jaeger backend will merge multiple instances of the spans with the same IDs).
+// Must be the lone reference, can be used only for root spans
 opentracing::SpanReference SelfRef(const opentracing::SpanContext* span_context) noexcept;
 
 }  // namespace jaegertracing