Document approach for multiple reject-if-present test

cmd/restic/exclude_test.go

@@ -84,35 +84,57 @@ func TestIsExcludedByFile(t *testing.T) {
 	}
 }
 
+// TestMultipleIsExcludedByFile is for testing that multiple instances of
+// the --exclude-if-present parameter (or the shortcut --exclude-caches do not
+// cancel each other out. It was initially written to demonstrate a bug in
+// rejectIfPresent.
 func TestMultipleIsExcludedByFile(t *testing.T) {
 	tempDir, cleanup := test.TempDir(t)
 	defer cleanup()
+
+	// Create some files in a temporary directory.
+	// Files in UPPERCASE will be used as exclusion triggers later on.
+	// We will test the inclusion later, so we add the expected value as
+	// a bool.
 	files := []struct {
 		path string
 		incl bool
 	}{
 		{"42", true},
 
+		// everything in foodir except the NOFOO tagfile
+		// should not be included.
 		{"foodir/NOFOO", true},
 		{"foodir/foo", false},
 		{"foodir/foosub/underfoo", false},
 
+		// everything in bardir except the NOBAR tagfile
+		// should not be included.
 		{"bardir/NOBAR", true},
 		{"bardir/bar", false},
 		{"bardir/barsub/underbar", false},
 
+		// everything in bazdir should be included.
 		{"bazdir/baz", true},
 		{"bazdir/bazsub/underbaz", true},
 	}
 	var errs []error
 	for _, f := range files {
+		// create directories first, then the file
 		p := filepath.Join(tempDir, filepath.FromSlash(f.path))
 		errs = append(errs, os.MkdirAll(filepath.Dir(p), 0700))
 		errs = append(errs, ioutil.WriteFile(p, []byte(f.path), 0600))
 	}
-	test.OKs(t, errs)
+	test.OKs(t, errs) // see if anything went wrong during the creation
+
+	// create two rejection functions, one that tests for the NOFOO file
+	// and one for the NOBAR file
 	fooExclude, _ := rejectIfPresent("NOFOO")
 	barExclude, _ := rejectIfPresent("NOBAR")
+
+	// To mock the archiver scanning walk, we create filepath.WalkFn
+	// that tests against the two rejection functions and stores
+	// the result in a map against we can test later.
 	m := make(map[string]bool)
 	walk := func(p string, fi os.FileInfo, err error) error {
 		if err != nil {
@@ -121,6 +143,7 @@ func TestMultipleIsExcludedByFile(t *testing.T) {
 		excludedByFoo := fooExclude(p, fi)
 		excludedByBar := barExclude(p, fi)
 		excluded := excludedByFoo || excludedByBar
+		// the log message helps debugging in case the test fails
 		t.Logf("%q: %v || %v = %v", p, excludedByFoo, excludedByBar, excluded)
 		m[p] = !excluded
 		if excluded {
@@ -128,7 +151,10 @@ func TestMultipleIsExcludedByFile(t *testing.T) {
 		}
 		return nil
 	}
+	// walk through the temporary file and check the error
 	test.OK(t, filepath.Walk(tempDir, walk))
+
+	// compare whether the walk gave the expected values for the test cases
 	for _, f := range files {
 		p := filepath.Join(tempDir, filepath.FromSlash(f.path))
 		if m[p] != f.incl {