replication: document most important aspects of Endpoint interface

cmd/endpoint/endpoint.go

@@ -296,7 +296,6 @@ func (s Remote) Send(ctx context.Context, r *pdu.SendReq) (*pdu.SendRes, io.Read
 		rs.Close()
 		return nil, nil, err
 	}
-	// FIXME make sure the consumer will read the reader until the end...
 	return &res, rs, nil
 }
 

replication/fsrep/fsfsm.go

@@ -36,11 +36,19 @@ func getLogger(ctx context.Context) Logger {
 	return l
 }
 
+// A Sender is usually part of a github.com/zrepl/zrepl/replication.Endpoint.
 type Sender interface {
+	// If a non-nil io.ReadCloser is returned, it is guaranteed to be closed before
+	// any next call to the parent github.com/zrepl/zrepl/replication.Endpoint.
 	Send(ctx context.Context, r *pdu.SendReq) (*pdu.SendRes, io.ReadCloser, error)
 }
 
+// A Sender is usually part of a github.com/zrepl/zrepl/replication.Endpoint.
 type Receiver interface {
+	// Receive sends r and sendStream (the latter containing a ZFS send stream)
+	// to the parent github.com/zrepl/zrepl/replication.Endpoint.
+	// Implementors must guarantee that Close was called on sendStream before
+	// the call to Receive returns.
 	Receive(ctx context.Context, r *pdu.ReceiveReq, sendStream io.ReadCloser) error
 }
 

replication/mainfsm.go

@@ -84,9 +84,14 @@ func NewReplication() *Replication {
 	return &r
 }
 
+// Endpoint represents one side of the replication.
+//
+// An endpoint is either in Sender or Receiver mode, represented by the correspondingly
+// named interfaces defined in this package.
 type Endpoint interface {
 	// Does not include placeholder filesystems
 	ListFilesystems(ctx context.Context) ([]*pdu.Filesystem, error)
+	// FIXME document FilteredError handling
 	ListFilesystemVersions(ctx context.Context, fs string) ([]*pdu.FilesystemVersion, error) // fix depS
 }
 
@@ -100,6 +105,7 @@ type Receiver interface {
 	fsrep.Receiver
 }
 
+
 type FilteredError struct{ fs string }
 
 func NewFilteredError(fs string) *FilteredError {