Clarify the attribute package documentation and order/grouping

attribute/key.go

@@ -20,23 +20,30 @@ type Key string
 
 // Bool creates a KeyValue instance with a BOOL Value.
 //
-// If creating both key and a bool value at the same time, then
-// instead of calling Key(name).Bool(value) consider using a
-// convenience function provided by the api/key package -
-// key.Bool(name, value).
+// If creating both a key and value at the same time, use the provided
+// convenience function instead -- Bool(name, value).
 func (k Key) Bool(v bool) KeyValue {
 	return KeyValue{
 		Key:   k,
 		Value: BoolValue(v),
 	}
 }
 
+// Int creates a KeyValue instance with an INT64 Value.
+//
+// If creating both a key and value at the same time, use the provided
+// convenience function instead -- Int(name, value).
+func (k Key) Int(v int) KeyValue {
+	return KeyValue{
+		Key:   k,
+		Value: IntValue(v),
+	}
+}
+
 // Int64 creates a KeyValue instance with an INT64 Value.
 //
-// If creating both key and an int64 value at the same time, then
-// instead of calling Key(name).Int64(value) consider using a
-// convenience function provided by the api/key package -
-// key.Int64(name, value).
+// If creating both a key and value at the same time, use the provided
+// convenience function instead -- Int64(name, value).
 func (k Key) Int64(v int64) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -46,10 +53,8 @@ func (k Key) Int64(v int64) KeyValue {
 
 // Float64 creates a KeyValue instance with a FLOAT64 Value.
 //
-// If creating both key and a float64 value at the same time, then
-// instead of calling Key(name).Float64(value) consider using a
-// convenience function provided by the api/key package -
-// key.Float64(name, value).
+// If creating both a key and value at the same time, use the provided
+// convenience function instead -- Float64(name, value).
 func (k Key) Float64(v float64) KeyValue {
 	return KeyValue{
 		Key:   k,
@@ -59,44 +64,27 @@ func (k Key) Float64(v float64) KeyValue {
 
 // String creates a KeyValue instance with a STRING Value.
 //
-// If creating both key and a string value at the same time, then
-// instead of calling Key(name).String(value) consider using a
-// convenience function provided by the api/key package -
-// key.String(name, value).
+// If creating both a key and value at the same time, use the provided
+// convenience function instead -- String(name, value).
 func (k Key) String(v string) KeyValue {
 	return KeyValue{
 		Key:   k,
 		Value: StringValue(v),
 	}
 }
 
-// Int creates a KeyValue instance with an INT64 Value.
+// Array creates a KeyValue instance with an ARRAY Value.
 //
-// If creating both key and an int value at the same time, then
-// instead of calling Key(name).Int(value) consider using a
-// convenience function provided by the api/key package -
-// key.Int(name, value).
-func (k Key) Int(v int) KeyValue {
+// If creating both a key and value at the same time, use the provided
+// convenience function instead -- Array(name, value).
+func (k Key) Array(v interface{}) KeyValue {
 	return KeyValue{
 		Key:   k,
-		Value: IntValue(v),
+		Value: ArrayValue(v),
 	}
 }
 
 // Defined returns true for non-empty keys.
 func (k Key) Defined() bool {
 	return len(k) != 0
 }
-
-// Array creates a KeyValue instance with a ARRAY Value.
-//
-// If creating both key and a array value at the same time, then
-// instead of calling Key(name).String(value) consider using a
-// convenience function provided by the api/key package -
-// key.Array(name, value).
-func (k Key) Array(v interface{}) KeyValue {
-	return KeyValue{
-		Key:   k,
-		Value: ArrayValue(v),
-	}
-}

attribute/kv.go

@@ -31,26 +31,27 @@ func (kv KeyValue) Valid() bool {
 	return kv.Key != "" && kv.Value.Type() != INVALID
 }
 
-// Bool creates a new key-value pair with a passed name and a bool
-// value.
+// Bool creates a KeyValue with a BOOL Value type.
 func Bool(k string, v bool) KeyValue {
 	return Key(k).Bool(v)
 }
 
-// Int64 creates a new key-value pair with a passed name and an int64
-// value.
+// Int creates a KeyValue with an INT64 Value type.
+func Int(k string, v int) KeyValue {
+	return Key(k).Int(v)
+}
+
+// Int64 creates a KeyValue with a INT64 Value type.
 func Int64(k string, v int64) KeyValue {
 	return Key(k).Int64(v)
 }
 
-// Float64 creates a new key-value pair with a passed name and a float64
-// value.
+// Float64 creates a KeyValue with a FLOAT64 Value type.
 func Float64(k string, v float64) KeyValue {
 	return Key(k).Float64(v)
 }
 
-// String creates a new key-value pair with a passed name and a string
-// value.
+// String creates a KeyValue with a STRING Value type.
 func String(k, v string) KeyValue {
 	return Key(k).String(v)
 }
@@ -61,13 +62,6 @@ func Stringer(k string, v fmt.Stringer) KeyValue {
 	return Key(k).String(v.String())
 }
 
-// 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) KeyValue {
-	return Key(k).Int(v)
-}
-
 // Array creates a new key-value pair with a passed name and a array.
 // Only arrays of primitive type are supported.
 func Array(k string, v interface{}) KeyValue {

attribute/value.go

@@ -63,6 +63,11 @@ func BoolValue(v bool) Value {
 	}
 }
 
+// IntValue creates an INT64 Value.
+func IntValue(v int) Value {
+	return Int64Value(int64(v))
+}
+
 // Int64Value creates an INT64 Value.
 func Int64Value(v int64) Value {
 	return Value{
@@ -87,11 +92,6 @@ func StringValue(v string) Value {
 	}
 }
 
-// IntValue creates an INT64 Value.
-func IntValue(v int) Value {
-	return Int64Value(int64(v))
-}
-
 // ArrayValue creates an ARRAY value from an array or slice.
 // Only arrays or slices of bool, int, int64, float, float64, or string types are allowed.
 // Specifically, arrays  and slices can not contain other arrays, slices, structs, or non-standard