document api/core and api/key packages (#263)

api/core/doc.go

@@ -12,4 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// This package provides basic types used in OpenTelemetry - keys,
+// values, numbers and span contexts.
 package core // import "go.opentelemetry.io/api/core"

api/core/key.go

@@ -21,15 +21,20 @@ import (
 	"unsafe"
 )
 
+// Key represents the key part in key-value pairs. It's a string. The
+// allowed character set in the key depends on the use of the key.
 type Key string
 
+// KeyValue holds a key and value pair.
 type KeyValue struct {
 	Key   Key
 	Value Value
 }
 
+// ValueType describes the type of the data Value holds.
 type ValueType int
 
+// Value represents the value part in key-value pairs.
 type Value struct {
 	vtype    ValueType
 	numeric  uint64
@@ -38,17 +43,18 @@ type Value struct {
 }
 
 const (
-	INVALID ValueType = iota
-	BOOL
-	INT32
-	INT64
-	UINT32
-	UINT64
-	FLOAT32
-	FLOAT64
-	STRING
+	INVALID ValueType = iota // No value.
+	BOOL                     // Boolean value, use AsBool() to get it.
+	INT32                    // 32 bit signed integral value, use AsInt32() to get it.
+	INT64                    // 64 bit signed integral value, use AsInt64() to get it.
+	UINT32                   // 32 bit unsigned integral value, use AsUint32() to get it.
+	UINT64                   // 64 bit unsigned integral value, use AsUint64() to get it.
+	FLOAT32                  // 32 bit floating point value, use AsFloat32() to get it.
+	FLOAT64                  // 64 bit floating point value, use AsFloat64() to get it.
+	STRING                   // String value, use AsString() to get it.
 )
 
+// Bool creates a BOOL Value.
 func Bool(v bool) Value {
 	return Value{
 		vtype:   BOOL,
@@ -56,6 +62,7 @@ func Bool(v bool) Value {
 	}
 }
 
+// Int64 creates an INT64 Value.
 func Int64(v int64) Value {
 	return Value{
 		vtype:   INT64,
@@ -63,6 +70,7 @@ func Int64(v int64) Value {
 	}
 }
 
+// Uint64 creates a UINT64 Value.
 func Uint64(v uint64) Value {
 	return Value{
 		vtype:   UINT64,
@@ -70,6 +78,7 @@ func Uint64(v uint64) Value {
 	}
 }
 
+// Float64 creates a FLOAT64 Value.
 func Float64(v float64) Value {
 	return Value{
 		vtype:   FLOAT64,
@@ -77,6 +86,7 @@ func Float64(v float64) Value {
 	}
 }
 
+// Int32 creates an INT32 Value.
 func Int32(v int32) Value {
 	return Value{
 		vtype:   INT32,
@@ -84,6 +94,7 @@ func Int32(v int32) Value {
 	}
 }
 
+// Uint32 creates a UINT32 Value.
 func Uint32(v uint32) Value {
 	return Value{
 		vtype:   UINT32,
@@ -91,6 +102,7 @@ func Uint32(v uint32) Value {
 	}
 }
 
+// Float32 creates a FLOAT32 Value.
 func Float32(v float32) Value {
 	return Value{
 		vtype:   FLOAT32,
@@ -98,6 +110,7 @@ func Float32(v float32) Value {
 	}
 }
 
+// String creates a STRING Value.
 func String(v string) Value {
 	return Value{
 		vtype:    STRING,
@@ -105,6 +118,8 @@ func String(v string) Value {
 	}
 }
 
+// Int creates either an INT32 or an INT64 Value, depending on whether
+// the int type is 32 or 64 bits wide.
 func Int(v int) Value {
 	if unsafe.Sizeof(v) == 4 {
 		return Int32(int32(v))
@@ -112,6 +127,8 @@ func Int(v int) Value {
 	return Int64(int64(v))
 }
 
+// Uint creates either a UINT32 or a UINT64 Value, depending on
+// whether the uint type is 32 or 64 bits wide.
 func Uint(v uint) Value {
 	if unsafe.Sizeof(v) == 4 {
 		return Uint32(uint32(v))
@@ -119,6 +136,7 @@ func Uint(v uint) Value {
 	return Uint64(uint64(v))
 }
 
+// Bool creates a KeyValue instance with a BOOL Value.
 func (k Key) Bool(v bool) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -126,6 +144,7 @@ func (k Key) Bool(v bool) KeyValue {
 	}
 }
 
+// Int64 creates a KeyValue instance with an INT64 Value.
 func (k Key) Int64(v int64) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -133,6 +152,7 @@ func (k Key) Int64(v int64) KeyValue {
 	}
 }
 
+// Uint64 creates a KeyValue instance with a UINT64 Value.
 func (k Key) Uint64(v uint64) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -140,6 +160,7 @@ func (k Key) Uint64(v uint64) KeyValue {
 	}
 }
 
+// Float64 creates a KeyValue instance with a FLOAT64 Value.
 func (k Key) Float64(v float64) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -147,6 +168,7 @@ func (k Key) Float64(v float64) KeyValue {
 	}
 }
 
+// Int32 creates a KeyValue instance with an INT32 Value.
 func (k Key) Int32(v int32) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -154,6 +176,7 @@ func (k Key) Int32(v int32) KeyValue {
 	}
 }
 
+// Uint32 creates a KeyValue instance with a UINT32 Value.
 func (k Key) Uint32(v uint32) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -161,6 +184,7 @@ func (k Key) Uint32(v uint32) KeyValue {
 	}
 }
 
+// Float32 creates a KeyValue instance with a FLOAT32 Value.
 func (k Key) Float32(v float32) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -168,6 +192,7 @@ func (k Key) Float32(v float32) KeyValue {
 	}
 }
 
+// String creates a KeyValue instance with a STRING Value.
 func (k Key) String(v string) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -175,6 +200,8 @@ func (k Key) String(v string) KeyValue {
 	}
 }
 
+// Int creates a KeyValue instance with either an INT32 or an INT64
+// Value, depending on whether the int type is 32 or 64 bits wide.
 func (k Key) Int(v int) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -182,6 +209,8 @@ func (k Key) Int(v int) KeyValue {
 	}
 }
 
+// Uint creates a KeyValue instance with either an UINT32 or an UINT64
+// Value, depending on whether the uint type is 32 or 64 bits wide.
 func (k Key) Uint(v uint) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -189,48 +218,67 @@ func (k Key) Uint(v uint) KeyValue {
 	}
 }
 
+// Defined returns true for non-empty keys.
 func (k Key) Defined() bool {
 	return len(k) != 0
 }
 
+// Type returns a type of the Value.
 func (v *Value) Type() ValueType {
 	return v.vtype
 }
 
+// Bool returns the bool value. Make sure that the Value's type is
+// BOOL.
 func (v *Value) AsBool() bool {
 	return rawToBool(v.numeric)
 }
 
+// AsInt32 returns the int32 value. Make sure that the Value's type is
+// INT32.
 func (v *Value) AsInt32() int32 {
 	return rawToInt32(v.numeric)
 }
 
+// AsInt64 returns the int64 value. Make sure that the Value's type is
+// INT64.
 func (v *Value) AsInt64() int64 {
 	return rawToInt64(v.numeric)
 }
 
+// AsUint32 returns the uint32 value. Make sure that the Value's type
+// is UINT32.
 func (v *Value) AsUint32() uint32 {
 	return rawToUint32(v.numeric)
 }
 
+// AsUint64 returns the uint64 value. Make sure that the Value's type is
+// UINT64.
 func (v *Value) AsUint64() uint64 {
 	return rawToUint64(v.numeric)
 }
 
+// AsFloat32 returns the float32 value. Make sure that the Value's
+// type is FLOAT32.
 func (v *Value) AsFloat32() float32 {
 	return rawToFloat32(v.numeric)
 }
 
+// AsFloat64 returns the float64 value. Make sure that the Value's
+// type is FLOAT64.
 func (v *Value) AsFloat64() float64 {
 	return rawToFloat64(v.numeric)
 }
 
+// AsString returns the string value. Make sure that the Value's type
+// is STRING.
 func (v *Value) AsString() string {
 	return v.stringly
 }
 
 type unknownValueType struct{}
 
+// AsInterface returns Value's data as interface{}.
 func (v *Value) AsInterface() interface{} {
 	switch v.Type() {
 	case BOOL:
@@ -253,6 +301,7 @@ func (v *Value) AsInterface() interface{} {
 	return unknownValueType{}
 }
 
+// Emit returns a string representation of Value's data.
 func (v *Value) Emit() string {
 	if v.Type() == STRING {
 		return v.stringly

api/core/number.go

@@ -62,14 +62,13 @@ func NewUint64Number(u uint64) Number {
 
 // - as x
 
-// AsNumber gets the raw, uninterpreted raw value. Might be useful for
-// some atomic operations.
+// AsNumber gets the Number.
 func (n Number) AsNumber() Number {
 	return n
 }
 
-// AsRaw gets the raw, uninterpreted raw value. Might be useful for
-// some atomic operations.
+// AsRaw gets the uninterpreted raw value. Might be useful for some
+// atomic operations.
 func (n Number) AsRaw() uint64 {
 	return uint64(n)
 }
@@ -94,32 +93,31 @@ func (n Number) AsUint64() uint64 {
 
 // - as x atomic
 
-// AsNumberAtomic gets the raw, uninterpreted raw value. Might be useful for
-// some atomic operations.
+// AsNumberAtomic gets the Number atomically.
 func (n *Number) AsNumberAtomic() Number {
 	return NewNumberFromRaw(n.AsRawAtomic())
 }
 
-// AsRawAtomic gets atomically the raw, uninterpreted raw value. Might
-// be useful for some atomic operations.
+// AsRawAtomic gets the uninterpreted raw value atomically. Might be
+// useful for some atomic operations.
 func (n *Number) AsRawAtomic() uint64 {
 	return atomic.LoadUint64(n.AsRawPtr())
 }
 
-// AsInt64Atomic assumes that the number contains an int64 and
-// atomically returns it as such.
+// AsInt64Atomic assumes that the number contains an int64 and returns
+// it as such atomically.
 func (n *Number) AsInt64Atomic() int64 {
 	return atomic.LoadInt64(n.AsInt64Ptr())
 }
 
-// AsFloat64 assumes that the measurement value contains a float64 and
-// returns it as such.
+// AsFloat64Atomic assumes that the measurement value contains a
+// float64 and returns it as such atomically.
 func (n *Number) AsFloat64Atomic() float64 {
 	return rawToFloat64(n.AsRawAtomic())
 }
 
-// AsUint64Atomic assumes that the number contains an uint64 and
-// atomically returns it as such.
+// AsUint64Atomic assumes that the number contains a uint64 and
+// returns it as such atomically.
 func (n *Number) AsUint64Atomic() uint64 {
 	return atomic.LoadUint64(n.AsUint64Ptr())
 }
@@ -132,20 +130,28 @@ func (n *Number) AsRawPtr() *uint64 {
 	return (*uint64)(n)
 }
 
+// AsInt64Ptr assumes that the number contains an int64 and returns a
+// pointer to it.
 func (n *Number) AsInt64Ptr() *int64 {
 	return rawPtrToInt64Ptr(n.AsRawPtr())
 }
 
+// AsFloat64Ptr assumes that the number contains a float64 and returns a
+// pointer to it.
 func (n *Number) AsFloat64Ptr() *float64 {
 	return rawPtrToFloat64Ptr(n.AsRawPtr())
 }
 
+// AsUint64Ptr assumes that the number contains a uint64 and returns a
+// pointer to it.
 func (n *Number) AsUint64Ptr() *uint64 {
 	return rawPtrToUint64Ptr(n.AsRawPtr())
 }
 
 // - coerce
 
+// CoerceToInt64 casts the number to int64. May result in
+// data/precision loss.
 func (n Number) CoerceToInt64(kind NumberKind) int64 {
 	switch kind {
 	case Int64NumberKind:
@@ -160,6 +166,8 @@ func (n Number) CoerceToInt64(kind NumberKind) int64 {
 	}
 }
 
+// CoerceToFloat64 casts the number to float64. May result in
+// data/precision loss.
 func (n Number) CoerceToFloat64(kind NumberKind) float64 {
 	switch kind {
 	case Int64NumberKind:
@@ -174,6 +182,8 @@ func (n Number) CoerceToFloat64(kind NumberKind) float64 {
 	}
 }
 
+// CoerceToUint64 casts the number to uint64. May result in
+// data/precision loss.
 func (n Number) CoerceToUint64(kind NumberKind) uint64 {
 	switch kind {
 	case Int64NumberKind:
@@ -190,74 +200,107 @@ func (n Number) CoerceToUint64(kind NumberKind) uint64 {
 
 // - set
 
+// SetNumber sets the number to the passed number. Both should be of
+// the same kind.
 func (n *Number) SetNumber(nn Number) {
 	*n.AsRawPtr() = nn.AsRaw()
 }
 
+// SetRaw sets the number to the passed raw value. Both number and the
+// raw number should represent the same kind.
 func (n *Number) SetRaw(r uint64) {
 	*n.AsRawPtr() = r
 }
 
+// SetInt64 assumes that the number contains an int64 and sets it to
+// the passed value.
 func (n *Number) SetInt64(i int64) {
 	*n.AsInt64Ptr() = i
 }
 
+// SetFloat64 assumes that the number contains a float64 and sets it
+// to the passed value.
 func (n *Number) SetFloat64(f float64) {
 	*n.AsFloat64Ptr() = f
 }
 
+// SetUint64 assumes that the number contains a uint64 and sets it to
+// the passed value.
 func (n *Number) SetUint64(u uint64) {
 	*n.AsUint64Ptr() = u
 }
 
 // - set atomic
 
+// SetNumberAtomic sets the number to the passed number
+// atomically. Both should be of the same kind.
 func (n *Number) SetNumberAtomic(nn Number) {
 	atomic.StoreUint64(n.AsRawPtr(), nn.AsRaw())
 }
 
+// SetRawAtomic sets the number to the passed raw value
+// atomically. Both number and the raw number should represent the
+// same kind.
 func (n *Number) SetRawAtomic(r uint64) {
 	atomic.StoreUint64(n.AsRawPtr(), r)
 }
 
+// SetInt64Atomic assumes that the number contains an int64 and sets
+// it to the passed value atomically.
 func (n *Number) SetInt64Atomic(i int64) {
 	atomic.StoreInt64(n.AsInt64Ptr(), i)
 }
 
+// SetFloat64Atomic assumes that the number contains a float64 and
+// sets it to the passed value atomically.
 func (n *Number) SetFloat64Atomic(f float64) {
 	atomic.StoreUint64(n.AsRawPtr(), float64ToRaw(f))
 }
 
+// SetUint64Atomic assumes that the number contains a uint64 and sets
+// it to the passed value atomically.
 func (n *Number) SetUint64Atomic(u uint64) {
 	atomic.StoreUint64(n.AsUint64Ptr(), u)
 }
 
 // - swap
 
+// SwapNumber sets the number to the passed number and returns the old
+// number. Both this number and the passed number should be of the
+// same kind.
 func (n *Number) SwapNumber(nn Number) Number {
 	old := *n
 	n.SetNumber(nn)
 	return old
 }
 
+// SwapRaw sets the number to the passed raw value and returns the old
+// raw value. Both number and the raw number should represent the same
+// kind.
 func (n *Number) SwapRaw(r uint64) uint64 {
 	old := n.AsRaw()
 	n.SetRaw(r)
 	return old
 }
 
+// SwapInt64 assumes that the number contains an int64, sets it to the
+// passed value and returns the old int64 value.
 func (n *Number) SwapInt64(i int64) int64 {
 	old := n.AsInt64()
 	n.SetInt64(i)
 	return old
 }
 
+// SwapFloat64 assumes that the number contains an float64, sets it to
+// the passed value and returns the old float64 value.
 func (n *Number) SwapFloat64(f float64) float64 {
 	old := n.AsFloat64()
 	n.SetFloat64(f)
 	return old
 }
 
+// SwapUint64 assumes that the number contains an uint64, sets it to
+// the passed value and returns the old uint64 value.
 func (n *Number) SwapUint64(u uint64) uint64 {
 	old := n.AsUint64()
 	n.SetUint64(u)
@@ -266,28 +309,43 @@ func (n *Number) SwapUint64(u uint64) uint64 {
 
 // - swap atomic
 
+// SwapNumberAtomic sets the number to the passed number and returns
+// the old number atomically. Both this number and the passed number
+// should be of the same kind.
 func (n *Number) SwapNumberAtomic(nn Number) Number {
 	return NewNumberFromRaw(atomic.SwapUint64(n.AsRawPtr(), nn.AsRaw()))
 }
 
+// SwapRawAtomic sets the number to the passed raw value and returns
+// the old raw value atomically. Both number and the raw number should
+// represent the same kind.
 func (n *Number) SwapRawAtomic(r uint64) uint64 {
 	return atomic.SwapUint64(n.AsRawPtr(), r)
 }
 
+// SwapInt64Atomic assumes that the number contains an int64, sets it
+// to the passed value and returns the old int64 value atomically.
 func (n *Number) SwapInt64Atomic(i int64) int64 {
 	return atomic.SwapInt64(n.AsInt64Ptr(), i)
 }
 
+// SwapFloat64Atomic assumes that the number contains an float64, sets
+// it to the passed value and returns the old float64 value
+// atomically.
 func (n *Number) SwapFloat64Atomic(f float64) float64 {
 	return rawToFloat64(atomic.SwapUint64(n.AsRawPtr(), float64ToRaw(f)))
 }
 
+// SwapUint64Atomic assumes that the number contains an uint64, sets
+// it to the passed value and returns the old uint64 value atomically.
 func (n *Number) SwapUint64Atomic(u uint64) uint64 {
 	return atomic.SwapUint64(n.AsUint64Ptr(), u)
 }
 
 // - add
 
+// AddNumber assumes that this and the passed number are of the passed
+// kind and adds the passed number to this number.
 func (n *Number) AddNumber(kind NumberKind, nn Number) {
 	switch kind {
 	case Int64NumberKind:
@@ -299,24 +357,34 @@ func (n *Number) AddNumber(kind NumberKind, nn Number) {
 	}
 }
 
+// AddRaw assumes that this number and the passed raw value are of the
+// passed kind and adds the passed raw value to this number.
 func (n *Number) AddRaw(kind NumberKind, r uint64) {
 	n.AddNumber(kind, NewNumberFromRaw(r))
 }
 
+// AddInt64 assumes that the number contains an int64 and adds the
+// passed int64 to it.
 func (n *Number) AddInt64(i int64) {
 	*n.AsInt64Ptr() += i
 }
 
+// AddFloat64 assumes that the number contains a float64 and adds the
+// passed float64 to it.
 func (n *Number) AddFloat64(f float64) {
 	*n.AsFloat64Ptr() += f
 }
 
+// AddUint64 assumes that the number contains a uint64 and adds the
+// passed uint64 to it.
 func (n *Number) AddUint64(u uint64) {
 	*n.AsUint64Ptr() += u
 }
 
 // - add atomic
 
+// AddNumberAtomic assumes that this and the passed number are of the
+// passed kind and adds the passed number to this number atomically.
 func (n *Number) AddNumberAtomic(kind NumberKind, nn Number) {
 	switch kind {
 	case Int64NumberKind:
@@ -328,14 +396,21 @@ func (n *Number) AddNumberAtomic(kind NumberKind, nn Number) {
 	}
 }
 
+// AddRawAtomic assumes that this number and the passed raw value are
+// of the passed kind and adds the passed raw value to this number
+// atomically.
 func (n *Number) AddRawAtomic(kind NumberKind, r uint64) {
 	n.AddNumberAtomic(kind, NewNumberFromRaw(r))
 }
 
+// AddInt64Atomic assumes that the number contains an int64 and adds
+// the passed int64 to it atomically.
 func (n *Number) AddInt64Atomic(i int64) {
 	atomic.AddInt64(n.AsInt64Ptr(), i)
 }
 
+// AddFloat64Atomic assumes that the number contains a float64 and
+// adds the passed float64 to it atomically.
 func (n *Number) AddFloat64Atomic(f float64) {
 	for {
 		o := n.AsFloat64Atomic()
@@ -345,28 +420,42 @@ func (n *Number) AddFloat64Atomic(f float64) {
 	}
 }
 
+// AddUint64Atomic assumes that the number contains a uint64 and
+// atomically adds the passed uint64 to it.
 func (n *Number) AddUint64Atomic(u uint64) {
 	atomic.AddUint64(n.AsUint64Ptr(), u)
 }
 
 // - compare and swap (atomic only)
 
+// CompareAndSwapNumber does the atomic CAS operation on this
+// number. This number and passed old and new numbers should be of the
+// same kind.
 func (n *Number) CompareAndSwapNumber(on, nn Number) bool {
 	return atomic.CompareAndSwapUint64(n.AsRawPtr(), on.AsRaw(), nn.AsRaw())
 }
 
+// CompareAndSwapRaw does the atomic CAS operation on this
+// number. This number and passed old and new raw values should be of
+// the same kind.
 func (n *Number) CompareAndSwapRaw(or, nr uint64) bool {
 	return atomic.CompareAndSwapUint64(n.AsRawPtr(), or, nr)
 }
 
+// CompareAndSwapInt64 assumes that this number contains an int64 and
+// does the atomic CAS operation on it.
 func (n *Number) CompareAndSwapInt64(oi, ni int64) bool {
 	return atomic.CompareAndSwapInt64(n.AsInt64Ptr(), oi, ni)
 }
 
+// CompareAndSwapFloat64 assumes that this number contains a float64 and
+// does the atomic CAS operation on it.
 func (n *Number) CompareAndSwapFloat64(of, nf float64) bool {
 	return atomic.CompareAndSwapUint64(n.AsRawPtr(), float64ToRaw(of), float64ToRaw(nf))
 }
 
+// CompareAndSwapUint64 assumes that this number contains a uint64 and
+// does the atomic CAS operation on it.
 func (n *Number) CompareAndSwapUint64(ou, nu uint64) bool {
 	return atomic.CompareAndSwapUint64(n.AsUint64Ptr(), ou, nu)
 }

api/core/span_context.go

@@ -44,30 +44,38 @@ func (e errorConst) Error() string {
 	return string(e)
 }
 
+// TraceID is a unique identity of a trace.
 type TraceID [16]byte
 
 var nilTraceID TraceID
 var _ json.Marshaler = nilTraceID
 
+// IsValid checks whether the trace ID is valid. A valid trace ID does
+// not consist of zeros only.
 func (t TraceID) IsValid() bool {
 	return !bytes.Equal(t[:], nilTraceID[:])
 }
 
-// MarshalJSON implements a custom marshal function to encode TraceID as a hex string
+// MarshalJSON implements a custom marshal function to encode TraceID
+// as a hex string.
 func (t TraceID) MarshalJSON() ([]byte, error) {
 	return json.Marshal(hex.EncodeToString(t[:]))
 }
 
+// SpanID is a unique identify of a span in a trace.
 type SpanID [8]byte
 
 var nilSpanID SpanID
 var _ json.Marshaler = nilSpanID
 
+// IsValid checks whether the span ID is valid. A valid span ID does
+// not consist of zeros only.
 func (s SpanID) IsValid() bool {
 	return !bytes.Equal(s[:], nilSpanID[:])
 }
 
-// MarshalJSON implements a custom marshal function to encode SpanID as a hex string
+// MarshalJSON implements a custom marshal function to encode SpanID
+// as a hex string.
 func (s SpanID) MarshalJSON() ([]byte, error) {
 	return json.Marshal(hex.EncodeToString(s[:]))
 }
@@ -131,38 +139,49 @@ func decodeHex(h string, b []byte) error {
 	return nil
 }
 
+// SpanContext contains basic information about the span - its trace
+// ID, span ID and trace flags.
 type SpanContext struct {
 	TraceID    TraceID
 	SpanID     SpanID
 	TraceFlags byte
 }
 
-// EmptySpanContext is meant for internal use to return invalid span context during error conditions.
+// EmptySpanContext is meant for internal use to return invalid span
+// context during error conditions.
 func EmptySpanContext() SpanContext {
 	return SpanContext{}
 }
 
+// IsValid checks if the span context is valid. A valid span context
+// has a valid trace ID and a valid span ID.
 func (sc SpanContext) IsValid() bool {
 	return sc.HasTraceID() && sc.HasSpanID()
 }
 
+// HasTraceID checks if the span context has a valid trace ID.
 func (sc SpanContext) HasTraceID() bool {
 	return sc.TraceID.IsValid()
 }
 
+// HasSpanID checks if the span context has a valid span ID.
 func (sc SpanContext) HasSpanID() bool {
 	return sc.SpanID.IsValid()
 }
 
+// SpanIDString returns a hex string representation of the span ID in
+// the span context.
 func (sc SpanContext) SpanIDString() string {
 	return hex.EncodeToString(sc.SpanID[:])
-
 }
 
+// TraceIDString returns a hex string representation of the trace ID
+// in the span context.
 func (sc SpanContext) TraceIDString() string {
 	return hex.EncodeToString(sc.TraceID[:])
 }
 
+// IsSampled check if the sampling bit in trace flags is set.
 func (sc SpanContext) IsSampled() bool {
 	return sc.TraceFlags&traceFlagsBitMaskSampled == traceFlagsBitMaskSampled
 }

api/key/doc.go

@@ -12,4 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// This package provides convenience functions for creating keys and
+// key-value pairs.
 package key // import "go.opentelemetry.io/api/key"

api/key/key.go

@@ -4,46 +4,69 @@ import (
 	"go.opentelemetry.io/api/core"
 )
 
+// New creates a new key with a passed name.
 func New(name string) core.Key {
 	return core.Key(name)
 }
 
+// Bool creates a new key-value pair with a passed name and a bool
+// value.
 func Bool(k string, v bool) core.KeyValue {
 	return New(k).Bool(v)
 }
 
+// Int64 creates a new key-value pair with a passed name and an int64
+// value.
 func Int64(k string, v int64) core.KeyValue {
 	return New(k).Int64(v)
 }
 
+// Uint64 creates a new key-value pair with a passed name and a uint64
+// value.
 func Uint64(k string, v uint64) core.KeyValue {
 	return New(k).Uint64(v)
 }
 
+// Float64 creates a new key-value pair with a passed name and a float64
+// value.
 func Float64(k string, v float64) core.KeyValue {
 	return New(k).Float64(v)
 }
 
+// Int32 creates a new key-value pair with a passed name and an int32
+// value.
 func Int32(k string, v int32) core.KeyValue {
 	return New(k).Int32(v)
 }
 
+// Uint32 creates a new key-value pair with a passed name and a uint32
+// value.
 func Uint32(k string, v uint32) core.KeyValue {
 	return New(k).Uint32(v)
 }
 
+// Float32 creates a new key-value pair with a passed name and a float32
+// value.
 func Float32(k string, v float32) core.KeyValue {
 	return New(k).Float32(v)
 }
 
+// String creates a new key-value pair with a passed name and a string
+// value.
 func String(k, v string) core.KeyValue {
 	return New(k).String(v)
 }
 
+// Int creates a new key-value pair instance with a passed name and
+// either an int32 or an int64 value, depending on whether the int
+// type is 32 or 64 bits wide.
 func Int(k string, v int) core.KeyValue {
 	return New(k).Int(v)
 }
 
+// Uint creates a new key-value pair instance with a passed name and
+// either an uint32 or an uint64 value, depending on whether the uint
+// type is 32 or 64 bits wide.
 func Uint(k string, v uint) core.KeyValue {
 	return New(k).Uint(v)
 }