Document tftypes package.

Author: Paddy Carver

tfprotov5/tftypes/attribute_path.go

@@ -6,48 +6,81 @@ import (
 )
 
 var (
+	// ErrNotAttributePathStepper is returned when a type that doesn't full
+	// the AttributePathStepper interface is passed to WalkAttributePath.
 	ErrNotAttributePathStepper = errors.New("doesn't fill tftypes.AttributePathStepper interface")
-	ErrInvalidStep             = errors.New("step cannot be applied to this value")
+
+	// ErrInvalidStep is returned when an AttributePath has the wrong kind
+	// of AttributePathStep for the type that WalkAttributePath is
+	// operating on.
+	ErrInvalidStep = errors.New("step cannot be applied to this value")
 )
 
+// AttributePath is a type that can point to a specific value within an
+// aggregate Terraform value. It consists of steps, each identifying one
+// element or attribute of the current value, and making that the current
+// value. This allows referring to arbitrarily precise values.
 type AttributePath struct {
+	// Steps are the steps that must be followed from the root of the value
+	// to obtain the value being indicated.
 	Steps []AttributePathStep
 }
 
+// NewErrorf returns an error associated with the value indicated by `a`. This
+// is equivalent to calling a.NewError(fmt.Errorf(f, args...)).
 func (a AttributePath) NewErrorf(f string, args ...interface{}) error {
 	return attributePathError{
 		error: fmt.Errorf(f, args...),
 		path:  a,
 	}
 }
 
+// NewError returns an error that associates `err` with the value indicated by
+// `a`.
 func (a AttributePath) NewError(err error) error {
 	return attributePathError{
 		error: err,
 		path:  a,
 	}
 }
 
+// WithAttributeName adds an AttributeName step to `a`, using `name` as the
+// attribute's name.
 func (a *AttributePath) WithAttributeName(name string) {
 	a.Steps = append(a.Steps, AttributeName(name))
 }
 
+// WithElementKeyString adds an ElementKeyString step to `a`, using `key` as
+// the element's key.
 func (a *AttributePath) WithElementKeyString(key string) {
 	a.Steps = append(a.Steps, ElementKeyString(key))
 }
 
+// WithElementKeyInt adds an ElementKeyInt step to `a`, using `key` as the
+// element's key.
 func (a *AttributePath) WithElementKeyInt(key int64) {
 	a.Steps = append(a.Steps, ElementKeyInt(key))
 }
 
+// WithElementKeyValue adds an ElementKeyValue to `a`, using `key` as the
+// element's key.
 func (a *AttributePath) WithElementKeyValue(key Value) {
 	a.Steps = append(a.Steps, ElementKeyValue(key))
 }
 
+// WithoutLastStep removes the last step, whatever kind of step it was, from
+// `a`.
 func (a *AttributePath) WithoutLastStep() {
 	a.Steps = a.Steps[:len(a.Steps)-1]
 }
 
+// AttributePathStep is an intentionally unimplementable interface that
+// functions as an enum, allowing us to use different strongly-typed step types
+// as a generic "step" type.
+//
+// An AttributePathStep is meant to indicate a single step in an AttributePath,
+// indicating a specific attribute or element that is the next value in the
+// path.
 type AttributePathStep interface {
 	unfulfillable() // make this interface fillable only by this package
 }
@@ -58,29 +91,53 @@ var (
 	_ AttributePathStep = ElementKeyInt(0)
 )
 
+// AttributeName is an AttributePathStep implementation that indicates the next
+// step in the AttributePath is to select an attribute. The value of the
+// AttributeName is the name of the attribute to be selected.
 type AttributeName string
 
 func (a AttributeName) unfulfillable() {}
 
+// ElementKeyString is an AttributePathStep implementation that indicates the
+// next step in the AttributePath is to select an element using a string key.
+// The value of the ElementKeyString is the key of the element to select.
 type ElementKeyString string
 
 func (e ElementKeyString) unfulfillable() {}
 
+// ElementKeyInt is an AttributePathStep implementation that indicates the next
+// step in the AttributePath is to select an element using an int64 key. The
+// value of the ElementKeyInt is the key of the element to select.
 type ElementKeyInt int64
 
 func (e ElementKeyInt) unfulfillable() {}
 
+// ElementKeyValue is an AttributePathStep implementation that indicates the
+// next step in the AttributePath is to select an element using the element
+// itself as a key. The value of the ElementKeyValue is the key of the element
+// to select.
 type ElementKeyValue Value
 
 func (e ElementKeyValue) unfulfillable() {}
 
+// AttributePathStepper is an interface that types can implement to make them
+// traversable by WalkAttributePath, allowing providers to retrieve the
+// specific value an AttributePath is pointing to.
 type AttributePathStepper interface {
 	// Return the attribute or element the AttributePathStep is referring
 	// to, or an error if the AttributePathStep is referring to an
 	// attribute or element that doesn't exist.
 	ApplyTerraform5AttributePathStep(AttributePathStep) (interface{}, error)
 }
 
+// WalkAttributePath will return the value that `path` is pointing to, using
+// `in` as the root. If an error is returned, the AttributePath returned will
+// indicate the steps that remained to be applied when the error was
+// encountered.
+//
+// map[string]interface{} and []interface{} types have built-in support. Other
+// types need to use the AttributePathStepper interface to tell
+// WalkAttributePath how to traverse themselves.
 func WalkAttributePath(in interface{}, path AttributePath) (interface{}, AttributePath, error) {
 	if len(path.Steps) < 1 {
 		return in, path, nil

tfprotov5/tftypes/doc.go

@@ -30,11 +30,15 @@
 // support using them as destinations for converted data:
 //
 // * String values can be converted into strings
+//
 // * Number values can be converted into *big.Floats
+//
 // * Boolean values can be converted into bools
+//
 // * List, Set, and Tuple values can be converted into a slice of Values
+//
 // * Map and Object values can be converted into a map with string keys and
-//   Value values.
+// Value values.
 //
 // These defaults were chosen because they're capable of losslessly
 // representing all possible values for their Terraform type, with the

tfprotov5/tftypes/list.go

@@ -2,10 +2,16 @@ package tftypes
 
 import "fmt"
 
+// List is a Terraform type representing an ordered collection of elements, all
+// of the same type.
 type List struct {
 	ElementType Type
 }
 
+// Is returns whether `t` is a List type or not. If `t` is an instance of the
+// List type and its ElementType property is nil, it will return true. If `t`'s
+// ElementType property is not nil, it will only return true if its ElementType
+// is considered the same type as `l`'s ElementType.
 func (l List) Is(t Type) bool {
 	v, ok := t.(List)
 	if !ok {
@@ -23,6 +29,8 @@ func (l List) String() string {
 
 func (l List) private() {}
 
+// MarshalJSON returns a JSON representation of the full type signature of `l`,
+// including its ElementType.
 func (l List) MarshalJSON() ([]byte, error) {
 	elementType, err := l.ElementType.MarshalJSON()
 	if err != nil {

tfprotov5/tftypes/map.go

@@ -2,10 +2,15 @@ package tftypes
 
 import "fmt"
 
+// Map is a Terraform type representing an unordered collection of elements,
+// all of the same type, each identifiable with a unique string key.
 type Map struct {
 	AttributeType Type
 }
 
+// Is returns whether `t` is a Map type or not. If `t` is an instance of the
+// Map type and its AttributeType property is not nil, it will only return true
+// if its AttributeType is considered the same type as `m`'s AttributeType.
 func (m Map) Is(t Type) bool {
 	v, ok := t.(Map)
 	if !ok {
@@ -23,6 +28,8 @@ func (m Map) String() string {
 
 func (m Map) private() {}
 
+// MarshalJSON returns a JSON representation of the full type signature of `m`,
+// including its AttributeType.
 func (m Map) MarshalJSON() ([]byte, error) {
 	attributeType, err := m.AttributeType.MarshalJSON()
 	if err != nil {

tfprotov5/tftypes/object.go

@@ -2,10 +2,20 @@ package tftypes
 
 import "encoding/json"
 
+// Object is a Terraform type representing an unordered collection of
+// attributes, potentially of differing types, each identifiable with a unique
+// string name. The number of attributes, their names, and their types are part
+// of the type signature for the Object, and so two Objects with different
+// attribute names or types are considered to be distinct types.
 type Object struct {
 	AttributeTypes map[string]Type
 }
 
+// Is returns whether `t` is an Object type or not. If `t` is an instance of
+// the Object type and its AttributeTypes property is not nil, it will only
+// return true the AttributeTypes are considered the same. To be considered
+// equal, the same set of keys must be present in each, and each key's value
+// needs to be considered the same type between the two Objects.
 func (o Object) Is(t Type) bool {
 	v, ok := t.(Object)
 	if !ok {
@@ -33,6 +43,8 @@ func (o Object) String() string {
 
 func (o Object) private() {}
 
+// MarshalJSON returns a JSON representation of the full type signature of `o`,
+// including the AttributeTypes.
 func (o Object) MarshalJSON() ([]byte, error) {
 	attrs, err := json.Marshal(o.AttributeTypes)
 	if err != nil {

tfprotov5/tftypes/primitive.go

@@ -3,11 +3,22 @@ package tftypes
 import "fmt"
 
 const (
-	UnknownType       = primitive("Unknown")
+	// DynamicPseudoType is a pseudo-type in Terraform's type system that
+	// is used as a wildcard type. It indicates that any Terraform type can
+	// be used.
 	DynamicPseudoType = primitive("DynamicPseudoType")
-	String            = primitive("String")
-	Number            = primitive("Number")
-	Bool              = primitive("Bool")
+
+	// String is a primitive type in Terraform that represents a UTF-8
+	// string of bytes.
+	String = primitive("String")
+
+	// Number is a primitive type in Terraform that represents a real
+	// number.
+	Number = primitive("Number")
+
+	// Bool is a primitive type in Terraform that represents a true or
+	// false boolean value.
+	Bool = primitive("Bool")
 )
 
 var (

tfprotov5/tftypes/set.go

@@ -2,10 +2,16 @@ package tftypes
 
 import "fmt"
 
+// Set is a Terraform type representing an unordered collection of unique
+// elements, all of the same type.
 type Set struct {
 	ElementType Type
 }
 
+// Is returns whether `t` is a Set type or not. If `t` is an instance of the
+// Set type and its ElementType property is nil, it will return true. If `t`'s
+// ElementType property is not nil, it will only return true if its ElementType
+// is considered the same type as `s`'s ElementType.
 func (s Set) Is(t Type) bool {
 	v, ok := t.(Set)
 	if !ok {
@@ -23,6 +29,8 @@ func (s Set) String() string {
 
 func (s Set) private() {}
 
+// MarshalJSON returns a JSON representation of the full type signature of `s`,
+// including its ElementType.
 func (s Set) MarshalJSON() ([]byte, error) {
 	elementType, err := s.ElementType.MarshalJSON()
 	if err != nil {

tfprotov5/tftypes/tuple.go

@@ -2,10 +2,20 @@ package tftypes
 
 import "encoding/json"
 
+// Tuple is a Terraform type representing an ordered collection of elements,
+// potentially of differing types. The number of elements and their types are
+// part of the type signature for the Tuple, and so two Tuples with different
+// numbers or types of elements are considered to be distinct types.
 type Tuple struct {
 	ElementTypes []Type
 }
 
+// Is returns whether `t` is a Tuple type or not. If `t` is an instance of the
+// Tuple type and its ElementTypes property is not nil, it will only return
+// true if the ElementTypes are considered the same. To be considered the same,
+// there must be the same number of ElementTypes, arranged in the same order,
+// and the types in each position must be considered the same as the type in
+// the same position in the other Tuple.
 func (tu Tuple) Is(t Type) bool {
 	v, ok := t.(Tuple)
 	if !ok {
@@ -30,6 +40,8 @@ func (tu Tuple) String() string {
 
 func (tu Tuple) private() {}
 
+// MarshalJSON returns a JSON representation of the full type signature of
+// `tu`, including the ElementTypes.
 func (tu Tuple) MarshalJSON() ([]byte, error) {
 	elements, err := json.Marshal(tu.ElementTypes)
 	if err != nil {

tfprotov5/tftypes/type.go

@@ -6,17 +6,36 @@ import (
 	"fmt"
 )
 
+// Type is an interface representing a Terraform type. It is only meant to be
+// implemented by the tftypes package. Types define the shape and
+// characteristics of data coming from or being sent to Terraform.
 type Type interface {
+	// Is is used to determine what type a Type implementation is. It is
+	// the recommended method for determining whether two types are
+	// equivalent or not.
 	Is(Type) bool
+
+	// String returns a string representation of the Type's name.
 	String() string
+
+	// MarshalJSON returns a JSON representation of the Type's signature.
+	// It is modeled based on Terraform's requirements for type signature
+	// JSON representations, and may change over time to match Terraform's
+	// formatting.
 	MarshalJSON() ([]byte, error)
+
+	// private is meant to keep this interface from being implemented by
+	// types from other packages.
 	private()
 }
 
 type jsonType struct {
 	t Type
 }
 
+// ParseJSONType returns a Type from its JSON representation. The JSON
+// representation should come from Terraform or from MarshalJSON as the format
+// is not part of this package's API guarantees.
 func ParseJSONType(buf []byte) (Type, error) {
 	var t jsonType
 	err := json.Unmarshal(buf, &t)

tfprotov5/tftypes/unknown_value.go

@@ -1,6 +1,8 @@
 package tftypes
 
 const (
+	// UnknownValue represents a value that is not yet known. It can be the
+	// value of any type.
 	UnknownValue = unknown(0)
 )