tests: Add documentation

src/restic/backend/test/benchmarks.go

@@ -24,6 +24,8 @@ func remove(t testing.TB, be restic.Backend, h restic.Handle) {
 	}
 }
 
+// BackendBenchmarkLoadFile benchmarks the Load() method of a backend by
+// loading a complete file.
 func BackendBenchmarkLoadFile(t *testing.B, s *Suite) {
 	be := s.open(t)
 	defer s.close(t, be)
@@ -62,6 +64,8 @@ func BackendBenchmarkLoadFile(t *testing.B, s *Suite) {
 	}
 }
 
+// BackendBenchmarkLoadPartialFile benchmarks the Load() method of a backend by
+// loading the remainder of a file starting at a given offset.
 func BackendBenchmarkLoadPartialFile(t *testing.B, s *Suite) {
 	be := s.open(t)
 	defer s.close(t, be)
@@ -103,6 +107,8 @@ func BackendBenchmarkLoadPartialFile(t *testing.B, s *Suite) {
 	}
 }
 
+// BackendBenchmarkLoadPartialFileOffset benchmarks the Load() method of a
+// backend by loading a number of bytes of a file starting at a given offset.
 func BackendBenchmarkLoadPartialFileOffset(t *testing.B, s *Suite) {
 	be := s.open(t)
 	defer s.close(t, be)
@@ -145,6 +151,7 @@ func BackendBenchmarkLoadPartialFileOffset(t *testing.B, s *Suite) {
 	}
 }
 
+// BackendBenchmarkSave benchmarks the Save() method of a backend.
 func BackendBenchmarkSave(t *testing.B, s *Suite) {
 	be := s.open(t)
 	defer s.close(t, be)

src/restic/backend/test/doc.go

@@ -0,0 +1,38 @@
+// Package test contains a test suite with benchmarks for restic backends.
+//
+// Overview
+//
+// For the test suite to work a few functions need to be implemented to create
+// new config, create a backend, open it and run cleanup tasks afterwards. The
+// Suite struct has fields for each function.
+//
+// So for a new backend, a Suite needs to be built with callback functions,
+// then the methods RunTests() and RunBenchmarks() can be used to run the
+// individual tests and benchmarks as subtests/subbenchmarks.
+//
+// Example
+//
+// Assuming a *Suite is returned by newTestSuite(), the tests and benchmarks
+// can be run like this:
+//
+//   func TestSuiteBackendMem(t *testing.T) {
+//   	newTestSuite(t).RunTests(t)
+//   }
+//
+//   func BenchmarkSuiteBackendMem(b *testing.B) {
+//   	newTestSuite(b).RunBenchmarks(b)
+//   }
+//
+// Add new tests
+//
+// A new test or benchmark can be added by implementing a function with a name
+// starting with BackendTest or BackendBenchmark. The first parameter is either
+// a testing.TB or *testing.T (for tests), or a *testing.B (for benchmarks).
+// The second parameter is a pointer to the test suite currently running
+// (*Suite).
+//
+// The list of functions to run is contained in the file funcs.go, which is
+// generated by generate_test_list.go. To regenerate that file, use go generate
+// restic/backend/test. Test/benchmark functions are run in the order they are
+// defined.
+package test

src/restic/backend/test/tests.go

@@ -1,4 +1,3 @@
-// Package test contains a test suite for restic backends.
 package test
 
 import (