Document 'pullsync' package (#871)

pkg/pullsync/doc.go

@@ -2,4 +2,18 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+/*
+Package pullsync contains protocol that is used to ensure that there is correct
+chunk replication in the neighborhood of the node.
+
+The protocol is used to exchange information about what chunks are stored on
+other nodes and if necessary pull any chunks it needs. It also takes care that
+chunks are not synced twice.
+
+The pullsync protocol uses Protobuf messages for encoding. It then exposes
+several functions which use those messages to start the exchange of other node
+cursors using `GetCursors` function, after which node can schedule syncing
+of chunks using `SyncInterval` function, and in the case of any errors or
+timed-out operations cancel syncing using `CancelRuid`.
+*/
 package pullsync

pkg/pullsync/pullsync.go

@@ -42,9 +42,17 @@ var (
 // how many maximum chunks in a batch
 var maxPage = 50
 
+// Interface is the PullSync interface.
 type Interface interface {
+	// SyncInterval syncs a requested interval from the given peer.
+	// It returns the BinID of highest chunk that was synced from the given
+	// interval. If the requested interval is too large, the downstream peer
+	// has the liberty to provide less chunks than requested.
 	SyncInterval(ctx context.Context, peer swarm.Address, bin uint8, from, to uint64) (topmost uint64, ruid uint32, err error)
+	// GetCursors retrieves all cursors from a downstream peer.
 	GetCursors(ctx context.Context, peer swarm.Address) ([]uint64, error)
+	// CancelRuid cancels active pullsync operation identified by ruid on
+	// a downstream peer.
 	CancelRuid(ctx context.Context, peer swarm.Address, ruid uint32) error
 }