diff --git a/tfexec/cmd.go b/tfexec/cmd.go
index 47e0e68..c3d8c11 100644
--- a/tfexec/cmd.go
+++ b/tfexec/cmd.go
@@ -11,7 +11,6 @@
 	"errors"
 	"fmt"
 	"io"
-	"io/ioutil"
 	"iter"
 	"os"
 	"os/exec"
@@ -123,6 +122,16 @@
 	return env
 }
 
+// buildEnv determines which environment variables should affect use of a Terraform
+// executable.
+//
+// Factors that can affect the final set of environment variables are:
+// > Whether a user has explicitly set environment variables via (tf *Terraform) SetEnv.
+// > The environment of the machine terraform-exec is run on.
+// > Any override ENVs set in command-specific code (e.g. use of TF_REATTACH_PROVIDERS).
+//
+// This method also enforces some rules for the entire terraform-exec library,
+// for example User Agent data set via ENVs.
 func (tf *Terraform) buildEnv(mergeEnv map[string]string) []string {
 	// set Terraform level env, if env is nil, fall back to os.Environ
 	var env map[string]string
@@ -312,7 +321,7 @@
 		}
 	}
 	if len(compact) == 0 {
-		return ioutil.Discard
+		return io.Discard
 	}
 	if len(compact) == 1 {
 		return compact[0]
diff --git a/tfexec/cmd_test.go b/tfexec/cmd_test.go
index c86dae3..ca5125a 100644
--- a/tfexec/cmd_test.go
+++ b/tfexec/cmd_test.go
@@ -49,6 +49,8 @@
 	}
 }
 
+// assertCmd asserts that a constructed exec.Cmd contains the expected args and environment variables.
+// The command itself isn't executed; that is only done in E2E tests.
 func assertCmd(t *testing.T, expectedArgs []string, expectedEnv map[string]string, actual *exec.Cmd) {
 	t.Helper()
 
diff --git a/tfexec/version.go b/tfexec/version.go
index 40b9301..880c7b3 100644
--- a/tfexec/version.go
+++ b/tfexec/version.go
@@ -166,7 +166,14 @@
 	return v.String()
 }
 
-// compatible asserts compatibility of the cached terraform version with the executable, and returns a well known error if not.
+// compatible asserts compatibility of the cached Terraform version with a set of constraints, and returns a well known error if not.
+//
+// Each command implementation with compatibility constraints will use this method to check that the available version of Terraform
+// is compatible with a given command, e.g. detect if a project consuming this library is attempting to use a flag that isn't present
+// in the Terraform binary it supplied. A common example is checking whether the version is sufficient to use the `-json` flag.
+//
+// Remember, terraform-exec is invoked with a path to an executable and has no way to know which version of Terraform it represents
+// until the executable is used.
 func (tf *Terraform) compatible(ctx context.Context, minInclusive *version.Version, maxExclusive *version.Version) error {
 	tfv, _, err := tf.Version(ctx, false)
 	if err != nil {