archiver: Add high-level documentation

internal/archiver/archiver.go

@@ -293,7 +293,8 @@ func (fn *FutureNode) wait(ctx context.Context) {
 }
 
 // Save saves a target (file or directory) to the repo. If the item is
-// excluded,this function returns a nil node and error.
+// excluded,this function returns a nil node and error, with excluded set to
+// true.
 //
 // Errors and completion is needs to be handled by the caller.
 //

internal/archiver/doc.go

@@ -0,0 +1,12 @@
+// Package archiver contains the code which reads files, splits them into
+// chunks and saves the data to the repository.
+//
+// An Archiver has a number of worker goroutines handling saving the different
+// data structures to the repository, the details are implemented by the
+// FileSaver, BlobSaver, and TreeSaver types.
+//
+// The main goroutine (the one calling Snapshot()) traverses the directory tree
+// and delegates all work to these worker pools. They return a type
+// (FutureFile, FutureBlob, and FutureTree) which can be resolved later, by
+// calling Wait() on it.
+package archiver