Merge pull request #6 from opentracing/changes/delint

delint

examples/dapperish/dapper.go

@@ -12,13 +12,14 @@ import (
 	"github.com/opentracing/api-golang/opentracing/standardtracer"
 )
 
+// NewTracer returns a new dapperish OpenTracer instance.
 func NewTracer(processName string) opentracing.OpenTracer {
 	return standardtracer.New(
 		NewTrivialRecorder(processName),
-		NewDapperishTraceContextSource())
+		NewTraceContextSource())
 }
 
-// An implementation of opentracing.TraceContext.
+// DapperishTraceContext is an implementation of opentracing.TraceContext.
 type DapperishTraceContext struct {
 	// A probabilistically unique identifier for a [multi-span] trace.
 	TraceID int64
@@ -38,12 +39,13 @@ type DapperishTraceContext struct {
 const (
 	// Note that these strings are designed to be unchanged by the conversion
 	// into standard HTTP headers (which messes with capitalization).
-	fieldNameTraceId   = "Traceid"
-	fieldNameSpanId    = "Spanid"
+	fieldNameTraceID   = "Traceid"
+	fieldNameSpanID    = "Spanid"
 	fieldNameSampled   = "Sampled"
 	fieldNameTagPrefix = "Tag-"
 )
 
+// NewChild complies with the opentracing.TraceContext interface.
 func (d *DapperishTraceContext) NewChild() (opentracing.TraceContext, opentracing.Tags) {
 	d.tagLock.RLock()
 	newTags := make(map[string]string, len(d.traceTags))
@@ -60,22 +62,7 @@ func (d *DapperishTraceContext) NewChild() (opentracing.TraceContext, opentracin
 	}, opentracing.Tags{"parent_span_id": d.SpanID}
 }
 
-// An implementation of opentracing.TraceContextSource.
-type DapperishTraceContextSource struct{}
-
-func NewDapperishTraceContextSource() *DapperishTraceContextSource {
-	return &DapperishTraceContextSource{}
-}
-
-func (m *DapperishTraceContextSource) NewRootTraceContext() opentracing.TraceContext {
-	return &DapperishTraceContext{
-		TraceID:   randomID(),
-		SpanID:    randomID(),
-		Sampled:   randomID()%1024 == 0,
-		traceTags: make(map[string]string),
-	}
-}
-
+// SetTraceTag complies with the opentracing.TraceContext interface.
 func (d *DapperishTraceContext) SetTraceTag(key, val string) opentracing.TraceContext {
 	d.tagLock.Lock()
 	defer d.tagLock.Unlock()
@@ -84,20 +71,43 @@ func (d *DapperishTraceContext) SetTraceTag(key, val string) opentracing.TraceCo
 	return d
 }
 
+// TraceTag complies with the opentracing.TraceContext interface.
 func (d *DapperishTraceContext) TraceTag(key string) string {
 	d.tagLock.RLock()
 	defer d.tagLock.RUnlock()
 
 	return d.traceTags[key]
 }
 
+// DapperishTraceContextSource is an implementation of
+// opentracing.TraceContextSource.
+type DapperishTraceContextSource struct{}
+
+// NewTraceContextSource returns a dapperish opentracing.TraceContextSource
+// implementation.
+func NewTraceContextSource() *DapperishTraceContextSource {
+	return &DapperishTraceContextSource{}
+}
+
+// NewRootTraceContext complies with the opentracing.TraceContextSource interface.
+func (d *DapperishTraceContextSource) NewRootTraceContext() opentracing.TraceContext {
+	return &DapperishTraceContext{
+		TraceID:   randomID(),
+		SpanID:    randomID(),
+		Sampled:   randomID()%1024 == 0,
+		traceTags: make(map[string]string),
+	}
+}
+
+// MarshalTraceContextStringMap complies with the
+// opentracing.TraceContextSource interface.
 func (d *DapperishTraceContextSource) MarshalTraceContextStringMap(
 	ctx opentracing.TraceContext,
 ) map[string]string {
 	dctx := ctx.(*DapperishTraceContext)
 	rval := map[string]string{
-		fieldNameTraceId: strconv.FormatInt(dctx.TraceID, 10),
-		fieldNameSpanId:  strconv.FormatInt(dctx.SpanID, 10),
+		fieldNameTraceID: strconv.FormatInt(dctx.TraceID, 10),
+		fieldNameSpanID:  strconv.FormatInt(dctx.SpanID, 10),
 		fieldNameSampled: strconv.FormatBool(dctx.Sampled),
 	}
 	dctx.tagLock.RLock()
@@ -108,6 +118,8 @@ func (d *DapperishTraceContextSource) MarshalTraceContextStringMap(
 	return rval
 }
 
+// UnmarshalTraceContextStringMap complies with the
+// opentracing.TraceContextSource interface.
 func (d *DapperishTraceContextSource) UnmarshalTraceContextStringMap(
 	encoded map[string]string,
 ) (opentracing.TraceContext, error) {
@@ -118,14 +130,14 @@ func (d *DapperishTraceContextSource) UnmarshalTraceContextStringMap(
 	var err error
 	for k, v := range encoded {
 		switch k {
-		case fieldNameTraceId:
-			traceID, err = strconv.ParseInt(encoded[fieldNameTraceId], 10, 64)
+		case fieldNameTraceID:
+			traceID, err = strconv.ParseInt(encoded[fieldNameTraceID], 10, 64)
 			if err != nil {
 				return nil, err
 			}
 			requiredFieldCount++
-		case fieldNameSpanId:
-			spanID, err = strconv.ParseInt(encoded[fieldNameSpanId], 10, 64)
+		case fieldNameSpanID:
+			spanID, err = strconv.ParseInt(encoded[fieldNameSpanID], 10, 64)
 			if err != nil {
 				return nil, err
 			}
@@ -156,6 +168,8 @@ func (d *DapperishTraceContextSource) UnmarshalTraceContextStringMap(
 	}, nil
 }
 
+// MarshalTraceContextBinary complies with the opentracing.TraceContextSource
+// interface.
 func (d *DapperishTraceContextSource) MarshalTraceContextBinary(ctx opentracing.TraceContext) []byte {
 	dtc := ctx.(*DapperishTraceContext)
 	// XXX: support tags
@@ -169,7 +183,7 @@ func (d *DapperishTraceContextSource) MarshalTraceContextBinary(ctx opentracing.
 	if err != nil {
 		panic(err)
 	}
-	var sampledByte byte = 0
+	var sampledByte byte
 	if dtc.Sampled {
 		sampledByte = 1
 	}
@@ -180,6 +194,8 @@ func (d *DapperishTraceContextSource) MarshalTraceContextBinary(ctx opentracing.
 	return buf.Bytes()
 }
 
+// UnmarshalTraceContextBinary complies with the opentracing.TraceContextSource
+// interface.
 func (d *DapperishTraceContextSource) UnmarshalTraceContextBinary(
 	encoded []byte,
 ) (opentracing.TraceContext, error) {

examples/dapperish/random.go

@@ -7,7 +7,7 @@ import (
 )
 
 var (
-	seededIDGen  *rand.Rand = rand.New(rand.NewSource(time.Now().UnixNano()))
+	seededIDGen  = rand.New(rand.NewSource(time.Now().UnixNano()))
 	seededIDLock sync.Mutex
 )
 

examples/dapperish/trivialrecorder.go

@@ -7,25 +7,30 @@ import (
 	"github.com/opentracing/api-golang/opentracing"
 )
 
+// TrivialRecorder implements the opentracing.Recorder interface.
 type TrivialRecorder struct {
 	processName string
 	tags        map[string]string
 }
 
+// NewTrivialRecorder returns a TrivialRecorder for the given `processName`.
 func NewTrivialRecorder(processName string) *TrivialRecorder {
 	return &TrivialRecorder{
 		processName: processName,
 		tags:        make(map[string]string),
 	}
 }
 
+// ProcessName complies with the opentracing.ProcessIdentifier interface.
 func (t *TrivialRecorder) ProcessName() string { return t.processName }
 
+// SetTag complies with the opentracing.ProcessIdentifier interface.
 func (t *TrivialRecorder) SetTag(key string, val interface{}) opentracing.ProcessIdentifier {
 	t.tags[key] = fmt.Sprint(val)
 	return t
 }
 
+// RecordSpan complies with the opentracing.Recorder interface.
 func (t *TrivialRecorder) RecordSpan(span *opentracing.RawSpan) {
 	fmt.Printf(
 		"RecordSpan: %v[%v, %v us] --> %v logs. trace context: %v\n",

opentracing/defaulttracer.go

@@ -4,52 +4,59 @@ var (
 	defaultOpenTracer OpenTracer = noopOpenTracer{noopTraceContextSource{}}
 )
 
-// Should be called as early as possible in main(), prior to calling the
-// `StartSpan*` (etc) global funcs below. Prior to calling `InitDefaultTracer`,
-// any Spans started via the `StartSpan*` globals are noops.
+// InitDefaultTracer sets the [singleton] OpenTracer returned by
+// DefaultTracer(). Those who use DefaultTracer (rather than directly manage an
+// OpenTracer instance) should call InitDefaultTracer as early as possible in
+// main(), prior to calling the `StartTrace` (etc) global funcs below. Prior to
+// calling `InitDefaultTracer`, any Spans started via the `StartTrace` (etc)
+// globals are noops.
 func InitDefaultTracer(tracer OpenTracer) {
 	defaultOpenTracer = tracer
 }
 
-// Return the global singleton `OpenTracer` implementation. Before
-// `InitDefaultTracer()` is called, the `DefaultTracer()` is a noop
+// DefaultTracer returns the global singleton `OpenTracer` implementation.
+// Before `InitDefaultTracer()` is called, the `DefaultTracer()` is a noop
 // implementation that drops all data handed to it.
 func DefaultTracer() OpenTracer {
 	return defaultOpenTracer
 }
 
-// Defers to `OpenTracer.StartTrace`. See `DefaultTracer()`.
+// StartTrace defers to `OpenTracer.StartTrace`. See `DefaultTracer()`.
 func StartTrace(operationName string, keyValueTags ...interface{}) Span {
 	return defaultOpenTracer.StartTrace(operationName, keyValueTags...)
 }
 
-// Defers to `OpenTracer.JoinTrace`. See `DefaultTracer()`.
+// JoinTrace defers to `OpenTracer.JoinTrace`. See `DefaultTracer()`.
 func JoinTrace(operationName string, parent interface{}, keyValueTags ...interface{}) Span {
 	return defaultOpenTracer.JoinTrace(operationName, parent, keyValueTags...)
 }
 
-// Defers to `TraceContextMarshaler.MarshalTraceContextBinary`.
+// MarshalTraceContextBinary defers to
+// `TraceContextMarshaler.MarshalTraceContextBinary`.
 //
 // See `DefaultTracer()`.
 func MarshalTraceContextBinary(ctx TraceContext) []byte {
 	return defaultOpenTracer.MarshalTraceContextBinary(ctx)
 }
 
-// Defers to `TraceContextMarshaler.MarshalStringMapTraceContext`.
+// MarshalTraceContextStringMap defers to
+// `TraceContextMarshaler.MarshalTraceContextStringMap`.
 //
 // See `DefaultTracer()`.
 func MarshalTraceContextStringMap(ctx TraceContext) map[string]string {
 	return defaultOpenTracer.MarshalTraceContextStringMap(ctx)
 }
 
-// Defers to `TraceContextUnmarshaler.UnmarshalTraceContextBinary`.
+// UnmarshalTraceContextBinary defers to
+// `TraceContextUnmarshaler.UnmarshalTraceContextBinary`.
 //
 // See `DefaultTracer()`.
 func UnmarshalTraceContextBinary(encoded []byte) (TraceContext, error) {
 	return defaultOpenTracer.UnmarshalTraceContextBinary(encoded)
 }
 
-// Defers to `TraceContextUnmarshaler.UnmarshalStringMapTraceContext`.
+// UnmarshalTraceContextStringMap defers to
+// `TraceContextUnmarshaler.UnmarshaTraceContextStringMap`.
 //
 // See `DefaultTracer()`.
 func UnmarshalTraceContextStringMap(encoded map[string]string) (TraceContext, error) {

opentracing/gocontext.go

@@ -6,18 +6,26 @@ type goContextKey int
 
 const activeSpanKey goContextKey = iota
 
-// Return a new `context.Context` including a reference to the given `Span`.
+// GoContextWithSpan seturns a new `context.Context` that holds a reference to
+// the given `Span`.
+//
+// NOTE: We use the term "GoContext" to minimize confusion with TraceContext.
 func GoContextWithSpan(ctx context.Context, span Span) context.Context {
 	return context.WithValue(ctx, activeSpanKey, span)
 }
 
-// A convenience wrapper around `GoContextWithSpan(context.BackgroundContext(), ...)`.
-func BackgroundContextWithSpan(span Span) context.Context {
+// BackgroundGoContextWithSpan is a convenience wrapper around
+// `GoContextWithSpan(context.BackgroundContext(), ...)`.
+//
+// NOTE: We use the term "GoContext" to minimize confusion with TraceContext.
+func BackgroundGoContextWithSpan(span Span) context.Context {
 	return context.WithValue(context.Background(), activeSpanKey, span)
 }
 
-// Returns the `Span` previously associated with `ctx`, or `nil` if no such
-// `Span` could be found.
+// SpanFromGoContext returns the `Span` previously associated with `ctx`, or
+// `nil` if no such `Span` could be found.
+//
+// NOTE: We use the term "GoContext" to minimize confusion with TraceContext.
 func SpanFromGoContext(ctx context.Context) Span {
 	val := ctx.Value(activeSpanKey)
 	if span, ok := val.(Span); ok {

opentracing/opentracer.go

@@ -1,7 +1,9 @@
 package opentracing
 
-// A simple, thin interface for Span creation. Though other implementations are
-// possible and plausible, most users will be fine with `NewStandardTracer()`.
+// OpenTracer is a simple, thin interface for Span creation.
+//
+// A straightforward implementation is available via the
+// `opentracing/standardtracer` package's `standardtracer.New()'.
 type OpenTracer interface {
 	TraceContextSource
 

opentracing/raw.go

@@ -2,8 +2,13 @@ package opentracing
 
 import "time"
 
+// Tags is a generic map from an arbitrary string key to an opaque value type.
+//
+// TODO: decide on restrictions (if any) for the values: just strings and POD?
+// just simple maps and slices of same? arbitrary objects?
 type Tags map[string]interface{}
 
+// RawSpan encapsulates all state associated with a (finished) Span.
 type RawSpan struct {
 	TraceContext
 
@@ -24,6 +29,7 @@ type RawSpan struct {
 	Logs []*RawLog
 }
 
+// RawLog encapsolutes all state associated with a log element in a Span.
 type RawLog struct {
 	Timestamp time.Time
 
@@ -44,7 +50,8 @@ type RawLog struct {
 	Payload interface{}
 }
 
-// Incorporate the keys and values from `other` into this `Tags` instance.
+// Merge incorporates the keys and values from `other` into this `Tags`
+// instance, then returns same.
 func (t Tags) Merge(other Tags) Tags {
 	for k, v := range other {
 		t[k] = v

opentracing/recorder.go

@@ -1,5 +1,8 @@
 package opentracing
 
+// ProcessIdentifier is a thin interface that guarantees all implementors
+// represent a ProcessName and accepts arbitrary process-level tag assignment
+// (e.g., build numbers, platforms, hostnames, etc).
 type ProcessIdentifier interface {
 	// Every process in the opentracing-instrumented distributed system must
 	// have a name.

opentracing/span.go

@@ -2,6 +2,9 @@ package opentracing
 
 import "golang.org/x/net/context"
 
+// Span represents an active, un-finished span in the opentracing system.
+//
+// Spans are created by the OpenTracer interface and Span.StartChild.
 type Span interface {
 	// Creates and starts a child span.
 	//
@@ -47,5 +50,8 @@ type Span interface {
 	//    var span Span = ...
 	//    goCtx := opentracing.GoContextWithSpan(ctx, span)
 	//
+	//
+	// NOTE: We use the term "GoContext" to minimize confusion with
+	// TraceContext.
 	AddToGoContext(goCtx context.Context) (Span, context.Context)
 }