Adding docs for config directory and variables (#150)

config/directory.go

@@ -9,12 +9,19 @@ import (
 	"testing"
 )
 
+// TestStepConfigFunc is the callback type used with acceptance tests to
+// specify a string which identifies a directory containing Terraform
+// configuration files.
 type TestStepConfigFunc func(TestStepConfigRequest) string
 
+// TestStepConfigRequest defines the request supplied to types
+// implementing TestStepConfigFunc.
 type TestStepConfigRequest struct {
 	StepNumber int
 }
 
+// Exec executes TestStepConfigFunc if it is not nil, otherwise an
+// empty string is returned.
 func (f TestStepConfigFunc) Exec(req TestStepConfigRequest) string {
 	if f != nil {
 		return f(req)
@@ -23,21 +30,29 @@ func (f TestStepConfigFunc) Exec(req TestStepConfigRequest) string {
 	return ""
 }
 
+// StaticDirectory is a helper function that returns the supplied
+// directory when TestStepConfigFunc is executed.
 func StaticDirectory(directory string) func(TestStepConfigRequest) string {
 	return func(_ TestStepConfigRequest) string {
 		return directory
 	}
 }
 
-//nolint:paralleltest //Not a test
-func TestNameDirectory(t *testing.T) func(TestStepConfigRequest) string {
+// TestNameDirectory returns the name of the test when TestStepConfigFunc
+// is executed. This facilitates a convention of naming directories
+// containing Terraform configuration files with the name of the test.
+func TestNameDirectory(t *testing.T) func(TestStepConfigRequest) string { //nolint:paralleltest //Not a test
 	return func(_ TestStepConfigRequest) string {
 		return t.Name()
 	}
 }
 
-//nolint:paralleltest //Not a test
-func TestStepDirectory(t *testing.T) func(TestStepConfigRequest) string {
+// TestStepDirectory returns the name of the test suffixed with an
+// OS specific separator and the test step number. This facilitates
+// a convention of naming directories containing Terraform
+// configuration files with the test step number and nesting of
+// these files within a directory with the same name as the test.
+func TestStepDirectory(t *testing.T) func(TestStepConfigRequest) string { //nolint:paralleltest //Not a test
 	return func(req TestStepConfigRequest) string {
 		return filepath.Join(t.Name(), strconv.Itoa(req.StepNumber))
 	}

config/variable.go

@@ -13,8 +13,17 @@ import (
 
 const autoTFVarsJson = "generated.auto.tfvars.json"
 
+// Variable interface is an alias to json.Marshaler.
+type Variable interface {
+	json.Marshaler
+}
+
+// Variables is a type holding a key-value map of variable names
+// to types implementing Variable interface.
 type Variables map[string]Variable
 
+// Write iterates over each element in v and assembles a JSON
+// file which is named autoTFVarsJson and written to dest.
 func (v Variables) Write(dest string) error {
 	buf := bytes.NewBuffer(nil)
 
@@ -49,80 +58,98 @@ func (v Variables) Write(dest string) error {
 	return nil
 }
 
-type Variable interface {
-	json.Marshaler
-}
-
-func BoolVariable(value bool) boolVariable {
-	return boolVariable{
-		value: value,
-	}
-}
+var _ Variable = boolVariable{}
 
 type boolVariable struct {
 	value bool
 }
 
+// MarshalJSON returns the JSON encoding of boolVariable.
 func (t boolVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
 
-func ListVariable(value ...Variable) listVariable {
-	return listVariable{
+// BoolVariable instantiates an instance of boolVariable,
+// which implements Variable.
+func BoolVariable(value bool) boolVariable {
+	return boolVariable{
 		value: value,
 	}
 }
 
+var _ Variable = listVariable{}
+
 type listVariable struct {
 	value []Variable
 }
 
+// MarshalJSON returns the JSON encoding of listVariable.
 func (t listVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
 
-func MapVariable(value map[string]Variable) mapVariable {
-	return mapVariable{
+// ListVariable instantiates an instance of listVariable,
+// which implements Variable.
+func ListVariable(value ...Variable) listVariable {
+	return listVariable{
 		value: value,
 	}
 }
 
+var _ Variable = mapVariable{}
+
 type mapVariable struct {
 	value map[string]Variable
 }
 
+// MarshalJSON returns the JSON encoding of mapVariable.
 func (t mapVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
 
-func ObjectVariable(value map[string]Variable) objectVariable {
-	return objectVariable{
+// MapVariable instantiates an instance of mapVariable,
+// which implements Variable.
+func MapVariable(value map[string]Variable) mapVariable {
+	return mapVariable{
 		value: value,
 	}
 }
 
+var _ Variable = objectVariable{}
+
 type objectVariable struct {
 	value map[string]Variable
 }
 
+// MarshalJSON returns the JSON encoding of objectVariable.
 func (t objectVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
 
-type number interface {
-	constraints.Float | constraints.Integer | *big.Float
-}
-
-func NumberVariable[T number](value T) numberVariable {
-	return numberVariable{
+// ObjectVariable instantiates an instance of objectVariable,
+// which implements Variable.
+func ObjectVariable(value map[string]Variable) objectVariable {
+	return objectVariable{
 		value: value,
 	}
 }
 
+var _ Variable = numberVariable{}
+
+type number interface {
+	constraints.Float | constraints.Integer | *big.Float
+}
+
 type numberVariable struct {
 	value any
 }
 
+// MarshalJSON returns the JSON encoding of numberVariable.
+// If the value of numberVariable is *bigFloat then the
+// representation of the value is the smallest number of
+// digits required to uniquely identify the value using the
+// precision of the *bigFloat that was supplied when
+// numberVariable was instantiated.
 func (t numberVariable) MarshalJSON() ([]byte, error) {
 	switch v := t.value.(type) {
 	case *big.Float:
@@ -132,36 +159,48 @@ func (t numberVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
 
-func SetVariable(value ...Variable) setVariable {
-	return setVariable{
+// NumberVariable instantiates an instance of numberVariable,
+// which implements Variable.
+func NumberVariable[T number](value T) numberVariable {
+	return numberVariable{
 		value: value,
 	}
 }
 
+var _ Variable = setVariable{}
+
 type setVariable struct {
 	value []Variable
 }
 
+// MarshalJSON returns the JSON encoding of setVariable.
 func (t setVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
 
-func StringVariable(value string) stringVariable {
-	return stringVariable{
+// SetVariable instantiates an instance of setVariable,
+// which implements Variable.
+func SetVariable(value ...Variable) setVariable {
+	return setVariable{
 		value: value,
 	}
 }
 
+var _ Variable = stringVariable{}
+
 type stringVariable struct {
 	value string
 }
 
+// MarshalJSON returns the JSON encoding of stringVariable.
 func (t stringVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
 
-func TupleVariable(value ...Variable) tupleVariable {
-	return tupleVariable{
+// StringVariable instantiates an instance of stringVariable,
+// which implements Variable.
+func StringVariable(value string) stringVariable {
+	return stringVariable{
 		value: value,
 	}
 }
@@ -170,6 +209,15 @@ type tupleVariable struct {
 	value []Variable
 }
 
+// MarshalJSON returns the JSON encoding of tupleVariable.
 func (t tupleVariable) MarshalJSON() ([]byte, error) {
 	return json.Marshal(t.value)
 }
+
+// TupleVariable instantiates an instance of tupleVariable,
+// which implements Variable.
+func TupleVariable(value ...Variable) tupleVariable {
+	return tupleVariable{
+		value: value,
+	}
+}