From 77a55fbe5c1a37ce67cdcd8e6364189d7b73ebaa Mon Sep 17 00:00:00 2001
From: Alexander Neumann <alexander@bumpern.de>
Date: Sun, 14 May 2017 10:58:09 +0200
Subject: [PATCH] tests: Add documentation

---
 src/restic/backend/test/benchmarks.go |  7 +++++
 src/restic/backend/test/doc.go        | 38 +++++++++++++++++++++++++++
 src/restic/backend/test/tests.go      |  1 -
 3 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 src/restic/backend/test/doc.go

diff --git a/src/restic/backend/test/benchmarks.go b/src/restic/backend/test/benchmarks.go
index 19831d96d..c9b5691f6 100644
--- a/src/restic/backend/test/benchmarks.go
+++ b/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)
diff --git a/src/restic/backend/test/doc.go b/src/restic/backend/test/doc.go
new file mode 100644
index 000000000..61cb835a7
--- /dev/null
+++ b/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
diff --git a/src/restic/backend/test/tests.go b/src/restic/backend/test/tests.go
index ff7d77549..aa24db970 100644
--- a/src/restic/backend/test/tests.go
+++ b/src/restic/backend/test/tests.go
@@ -1,4 +1,3 @@
-// Package test contains a test suite for restic backends.
 package test
 
 import (