package docs

Author: austinvalle

tftypes/refinement/collection_length_lower_bound.go

@@ -5,7 +5,8 @@ package refinement
 
 import "fmt"
 
-// TODO: doc
+// CollectionLengthLowerBound represents an unknown value refinement which indicates the length of the final collection value will be
+// at least the specified int64 value. This refinement can only be applied to List, Map, and Set types.
 type CollectionLengthLowerBound struct {
 	value int64
 }
@@ -23,14 +24,15 @@ func (n CollectionLengthLowerBound) String() string {
 	return fmt.Sprintf("length lower bound = %d", n.LowerBound())
 }
 
-// TODO: doc
+// LowerBound returns the int64 value that the final value's collection length will be at least.
 func (n CollectionLengthLowerBound) LowerBound() int64 {
 	return n.value
 }
 
 func (n CollectionLengthLowerBound) unimplementable() {}
 
-// TODO: doc
+// NewCollectionLengthLowerBound returns the CollectionLengthLowerBound unknown value refinement which indicates the length of the final
+// collection value will be at least the specified int64 value. This refinement can only be applied to List, Map, and Set types.
 func NewCollectionLengthLowerBound(value int64) Refinement {
 	return CollectionLengthLowerBound{
 		value: value,

tftypes/refinement/collection_length_upper_bound.go

@@ -5,7 +5,8 @@ package refinement
 
 import "fmt"
 
-// TODO: doc
+// CollectionLengthUpperBound represents an unknown value refinement which indicates the length of the final collection value will be
+// at most the specified int64 value. This refinement can only be applied to List, Map, and Set types.
 type CollectionLengthUpperBound struct {
 	value int64
 }
@@ -23,14 +24,15 @@ func (n CollectionLengthUpperBound) String() string {
 	return fmt.Sprintf("length upper bound = %d", n.UpperBound())
 }
 
-// TODO: doc
+// UpperBound returns the int64 value that the final value's collection length will be at most.
 func (n CollectionLengthUpperBound) UpperBound() int64 {
 	return n.value
 }
 
 func (n CollectionLengthUpperBound) unimplementable() {}
 
-// TODO: doc
+// NewCollectionLengthUpperBound returns the CollectionLengthUpperBound unknown value refinement which indicates the length of the final
+// collection value will be at most the specified int64 value. This refinement can only be applied to List, Map, and Set types.
 func NewCollectionLengthUpperBound(value int64) Refinement {
 	return CollectionLengthUpperBound{
 		value: value,

tftypes/refinement/doc.go

@@ -1,5 +1,11 @@
 // Copyright (c) HashiCorp, Inc.
 // SPDX-License-Identifier: MPL-2.0
 
-// TODO: docs
+// The refinement package contains the interfaces and structs that represent unknown value refinement data. Refinements contain
+// additional constraints about unknown values and what their eventual known values can be. In certain scenarios, Terraform can
+// use these constraints to produce known results from unknown values. (like evaluating a count expression comparing an unknown
+// value to "null")
+//
+// Unknown value refinements can be added to a `tftypes.Value` via the `(tftypes.Value).Refine` method. Refinements on an unknown
+// `tftypes.Value` can be retrieved via the `(tftypes.Value).Refinements()` method.
 package refinement

tftypes/refinement/nullness.go

@@ -3,7 +3,12 @@
 
 package refinement
 
-// TODO: doc
+// Nullness represents an unknown value refinement that indicates the final value will definitely not be null (Nullness = false). This refinement
+// can be applied to a value of any type (excluding DynamicPseudoType).
+//
+// While an unknown value can be refined to indicate that the final value will definitely be null (Nullness = true), there is no practical reason
+// to do this. This option is exposed to maintain parity with Terraform's type system, while all practical usages of this refinement should collapse
+// to known null values instead.
 type Nullness struct {
 	value bool
 }
@@ -27,14 +32,25 @@ func (n Nullness) String() string {
 	return "not null"
 }
 
-// TODO: doc
+// Nullness returns the underlying refinement data indicating:
+//   - When "false", the final value will definitely not be null.
+//   - When "true", the final value will definitely be null.
+//
+// While an unknown value can be refined to indicate that the final value will definitely be null (Nullness = true), there is no practical reason
+// to do this. This option is exposed to maintain parity with Terraform's type system, while all practical usages of this refinement should collapse
+// to known null values instead.
 func (n Nullness) Nullness() bool {
 	return n.value
 }
 
 func (n Nullness) unimplementable() {}
 
-// TODO: doc
+// NewNullness returns the Nullness unknown value refinement that indicates the final value will definitely not be null (Nullness = false). This refinement
+// can be applied to a value of any type (excluding DynamicPseudoType).
+//
+// While an unknown value can be refined to indicate that the final value will definitely be null (Nullness = true), there is no practical reason
+// to do this. This option is exposed to maintain parity with Terraform's type system, while all practical usages of this refinement should collapse
+// to known null values instead.
 func NewNullness(value bool) Refinement {
 	return Nullness{
 		value: value,

tftypes/refinement/number_lower_bound.go

@@ -8,7 +8,8 @@ import (
 	"math/big"
 )
 
-// TODO: doc
+// NumberLowerBound represents an unknown value refinement that indicates the final value will not be less than the specified
+// *big.Float value, as well as whether that bound is inclusive or exclusive. This refinement can only be applied to the Number type.
 type NumberLowerBound struct {
 	inclusive bool
 	value     *big.Float
@@ -32,19 +33,21 @@ func (n NumberLowerBound) String() string {
 	return fmt.Sprintf("lower bound = %s (%s)", n.LowerBound().String(), rangeDescription)
 }
 
-// TODO: doc
+// IsInclusive returns whether the bound returned by the `LowerBound` method is inclusive or exclusive.
 func (n NumberLowerBound) IsInclusive() bool {
 	return n.inclusive
 }
 
-// TODO: doc
+// LowerBound returns the *big.Float value that the final value will not be less than. The `IsInclusive` method must also be used during
+// comparison to determine whether the bound is inclusive or exclusive.
 func (n NumberLowerBound) LowerBound() *big.Float {
 	return n.value
 }
 
 func (n NumberLowerBound) unimplementable() {}
 
-// TODO: doc
+// NewNumberLowerBound returns the NumberLowerBound unknown value refinement that indicates the final value will not be less than the specified
+// *big.Float value, as well as whether that bound is inclusive or exclusive. This refinement can only be applied to the Number type.
 func NewNumberLowerBound(value *big.Float, inclusive bool) Refinement {
 	return NumberLowerBound{
 		value:     value,

tftypes/refinement/number_upper_bound.go

@@ -8,7 +8,8 @@ import (
 	"math/big"
 )
 
-// TODO: doc
+// NumberUpperBound represents an unknown value refinement that indicates the final value will not be greater than the specified
+// *big.Float value, as well as whether that bound is inclusive or exclusive. This refinement can only be applied to the Number type.
 type NumberUpperBound struct {
 	inclusive bool
 	value     *big.Float
@@ -32,19 +33,21 @@ func (n NumberUpperBound) String() string {
 	return fmt.Sprintf("upper bound = %s (%s)", n.UpperBound().String(), rangeDescription)
 }
 
-// TODO: doc
+// IsInclusive returns whether the bound returned by the `UpperBound` method is inclusive or exclusive.
 func (n NumberUpperBound) IsInclusive() bool {
 	return n.inclusive
 }
 
-// TODO: doc
+// UpperBound returns the *big.Float value that the final value will not be greater than. The `IsInclusive` method must also be used during
+// comparison to determine whether the bound is inclusive or exclusive.
 func (n NumberUpperBound) UpperBound() *big.Float {
 	return n.value
 }
 
 func (n NumberUpperBound) unimplementable() {}
 
-// TODO: doc
+// NewNumberUpperBound returns the NumberUpperBound unknown value refinement that indicates the final value will not be greater than the specified
+// *big.Float value, as well as whether that bound is inclusive or exclusive. This refinement can only be applied to the Number type.
 func NewNumberUpperBound(value *big.Float, inclusive bool) Refinement {
 	return NumberUpperBound{
 		value:     value,

tftypes/refinement/refinement.go

@@ -12,7 +12,6 @@ import (
 type Key int64
 
 func (k Key) String() string {
-	// TODO: Not sure when this is used, double check the names
 	switch k {
 	case KeyNullness:
 		return "nullness"
@@ -22,6 +21,10 @@ func (k Key) String() string {
 		return "number_lower_bound"
 	case KeyNumberUpperBound:
 		return "number_upper_bound"
+	case KeyCollectionLengthLowerBound:
+		return "collection_length_lower_bound"
+	case KeyCollectionLengthUpperBound:
+		return "collection_length_upper_bound"
 	default:
 		return fmt.Sprintf("unsupported refinement: %d", k)
 	}
@@ -65,7 +68,8 @@ const (
 	KeyCollectionLengthUpperBound = Key(6)
 )
 
-// TODO: docs
+// Refinement represents an unknown value refinement with data constraints relevant to the final value. This interface can be asserted further
+// with the associated structs in the `refinement` package to extract underlying refinement data.
 type Refinement interface {
 	// Equal should return true if the Refinement is considered equivalent to the
 	// Refinement passed as an argument.
@@ -77,7 +81,7 @@ type Refinement interface {
 	unimplementable() // prevents external implementations, all refinements are defined in the Terraform/HCL type system go-cty.
 }
 
-// TODO: docs
+// Refinements represents a map of unknown value refinement data.
 type Refinements map[Key]Refinement
 
 func (r Refinements) Equal(other Refinements) bool {

tftypes/refinement/string_prefix.go

@@ -5,7 +5,9 @@ package refinement
 
 import "fmt"
 
-// TODO: doc
+// StringPrefix represents an unknown value refinement that indicates the final value will be prefixed with the specified string value.
+// String prefixes that exceed 256 characters in length will be truncated and empty string prefixes will not be encoded. This refinement can
+// only be applied to the String type.
 type StringPrefix struct {
 	value string
 }
@@ -23,14 +25,16 @@ func (s StringPrefix) String() string {
 	return fmt.Sprintf("prefix = %q", s.PrefixValue())
 }
 
-// TODO: doc
+// PrefixValue returns the string value that the final value will be prefixed with.
 func (s StringPrefix) PrefixValue() string {
 	return s.value
 }
 
 func (s StringPrefix) unimplementable() {}
 
-// TODO: doc
+// NewStringPrefix returns the StringPrefix unknown value refinement that indicates the final value will be prefixed with the specified
+// string value. String prefixes that exceed 256 characters in length will be truncated and empty string prefixes will not be encoded. This
+// refinement can only be applied to the String type.
 func NewStringPrefix(value string) Refinement {
 	return StringPrefix{
 		value: value,

tftypes/value.go

@@ -42,8 +42,6 @@ type ValueCreator interface {
 // The recommended usage of a Value is to check that it is known, using
 // Value.IsKnown, then to convert it to a Go type, using Value.As. The Go type
 // can then be manipulated.
-//
-// TODO: add docs for new refinement data
 type Value struct {
 	typ   Type
 	value interface{}
@@ -628,7 +626,10 @@ func unexpectedValueTypeError(p *AttributePath, expected, got interface{}, typ T
 	return p.NewErrorf("unexpected value type %T, %s values must be of type %T", got, typ, expected)
 }
 
-// TODO: doc, mention returning value if not unknown
+// Refine is used to apply unknown refinement data to a Value. This method will return a copy of the Value, fully
+// replacing all the existing refinement data with the provided refinements.
+//
+// If the Value is not unknown, then a copy of the Value will be returned with no refinements.
 func (val Value) Refine(refinements refinement.Refinements) Value {
 	newVal := val.Copy()
 
@@ -648,8 +649,9 @@ func (val Value) Refine(refinements refinement.Refinements) Value {
 	return newVal
 }
 
-// TODO: doc, mention copy
+// Refinements returns the unknown refinement data for the Value.
 func (val Value) Refinements() refinement.Refinements {
+	// Copy the data first to prevent any mutation of the refinement map data.
 	valCopy := val.Copy()
 
 	return valCopy.refinements