util: shorten data type names and add doc example

test_test.go

@@ -1637,14 +1637,14 @@ func TestFileContains(t *testing.T) {
 		tc := newCase(t, `expected file contents`)
 		t.Cleanup(tc.assert)
 
-		path := util.TempFile(t, util.Pattern("test"), util.StringData("real data"))
+		path := util.TempFile(t, util.Pattern("test"), util.String("real data"))
 		FileContains(tc, path, "fake")
 	})
 	t.Run("file contains data", func(t *testing.T) {
 		tc := newCase(t, "")
 		t.Cleanup(tc.assertNot)
 
-		path := util.TempFile(t, util.Pattern("test"), util.StringData("real data"))
+		path := util.TempFile(t, util.Pattern("test"), util.String("real data"))
 		FileContains(tc, path, "real")
 	})
 }

util/examples_test.go

@@ -0,0 +1,25 @@
+// Copyright (c) The Test Authors
+// SPDX-License-Identifier: MPL-2.0
+
+package util_test
+
+import (
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/shoenig/test/util"
+)
+
+var t = new(testing.T)
+
+func ExampleTempFile() {
+	path := util.TempFile(t,
+		util.String("hello!"),
+		util.Mode(0o640),
+	)
+
+	b, _ := os.ReadFile(path)
+	fmt.Println(string(b))
+	// Output: hello!
+}

util/tempfile.go

@@ -1,6 +1,7 @@
 // Copyright (c) The Test Authors
 // SPDX-License-Identifier: MPL-2.0
 
+// Package util provides utility functions for writing concise test cases.
 package util
 
 import (
@@ -42,15 +43,15 @@ func Mode(mode fs.FileMode) TempFileSetting {
 	}
 }
 
-// StringData writes data to the temporary file.
-func StringData(data string) TempFileSetting {
+// String writes data to the temporary file.
+func String(data string) TempFileSetting {
 	return func(s *TempFileSettings) {
 		s.data = []byte(data)
 	}
 }
 
-// ByteData writes data to the temporary file.
-func ByteData(data []byte) TempFileSetting {
+// Bytes writes data to the temporary file.
+func Bytes(data []byte) TempFileSetting {
 	return func(s *TempFileSettings) {
 		s.data = data
 	}

util/tempfile_test.go

@@ -122,7 +122,7 @@ func TestTempFile(t *testing.T) {
 		path := util.TempFile(t,
 			util.Mode(expectedMode),
 			util.Pattern(pattern),
-			util.StringData(expectedData))
+			util.String(expectedData))
 
 		t.Run("Mode sets a custom file mode", func(t *testing.T) {
 			info, err := os.Stat(path)
@@ -150,9 +150,9 @@ func TestTempFile(t *testing.T) {
 		})
 	})
 
-	t.Run("ByteData sets binary data", func(t *testing.T) {
+	t.Run("Bytes sets binary data", func(t *testing.T) {
 		expectedData := []byte("important data")
-		path := util.TempFile(t, util.ByteData(expectedData))
+		path := util.TempFile(t, util.Bytes(expectedData))
 		actualData, err := os.ReadFile(path)
 		if err != nil {
 			t.Fatalf("failed to read temp file: %v", err)