clientv3: document context to "Watch" API
@@ -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.
