Merge pull request #9016 from gyuho/watch-doc

clientv3: document context to "Watch" API

.words

@@ -9,6 +9,7 @@ ResourceExhausted
 RPC
 RPCs
 TODO
+WithRequireLeader
 backoff
 blackhole
 blackholed

clientv3/watch.go

@@ -46,6 +46,20 @@ type Watcher interface {
 	// through the returned channel. If revisions waiting to be sent over the
 	// watch are compacted, then the watch will be canceled by the server, the
 	// client will post a compacted error watch response, and the channel will close.
+	// If the context "ctx" is canceled or timed out, returned "WatchChan" is closed,
+	// and "WatchResponse" from this closed channel has zero events and nil "Err()".
+	// If the context is "context.Background/TODO", returned "WatchChan" will not be closed
+	// and wait until events happen, except when server returns a non-recoverable error.
+	// For example, when context passed with "WithRequireLeader" and the connected server
+	// has no leader, error "etcdserver: no leader" is returned, and then "WatchChan" is
+	// closed with non-nil "Err()".
+	// Otherwise, as long as the context has not been canceled or timed out, watch will
+	// retry on other recoverable errors forever until reconnected.
+	//
+	// TODO: explicitly set context error in the last "WatchResponse" message and close channel?
+	// Currently, client contexts are overwritten with "valCtx" that never closes.
+	// TODO(v3.4): configure watch retry policy, limit maximum retry number
+	// (see https://github.com/coreos/etcd/issues/8980)
 	Watch(ctx context.Context, key string, opts ...OpOption) WatchChan
 
 	// Close closes the watcher and cancels all watch requests.