Merge pull request #119 from hashicorp/dnephin/docs-watch-set-errors

Document error return value of WatchSet.WatchCtx

watch.go

@@ -5,7 +5,8 @@ import (
 	"time"
 )
 
-// WatchSet is a collection of watch channels.
+// WatchSet is a collection of watch channels. The zero value is not usable.
+// Use NewWatchSet to create a WatchSet.
 type WatchSet map[<-chan struct{}]struct{}
 
 // NewWatchSet constructs a new watch set.
@@ -31,7 +32,7 @@ func (w WatchSet) Add(watchCh <-chan struct{}) {
 // not by much.
 //
 // This is useful if you want to track individual items up to some limit, after
-// which you watch a higher-level channel (usually a channel from start start of
+// which you watch a higher-level channel (usually a channel from start of
 // an iterator higher up in the radix tree) that will watch a superset of items.
 func (w WatchSet) AddWithLimit(softLimit int, watchCh <-chan struct{}, altCh <-chan struct{}) {
 	// This is safe for a nil WatchSet so we don't need to check that here.
@@ -42,8 +43,9 @@ func (w WatchSet) AddWithLimit(softLimit int, watchCh <-chan struct{}, altCh <-c
 	}
 }
 
-// Watch is used to wait for any channel of the watch set to trigger or a timeout.
-// Returns true on timeout.
+// Watch blocks until one of the channels in the watch set is closed, or
+// timeoutCh sends a value.
+// Returns true if timeoutCh is what caused Watch to unblock.
 func (w WatchSet) Watch(timeoutCh <-chan time.Time) bool {
 	if w == nil {
 		return false
@@ -64,9 +66,11 @@ func (w WatchSet) Watch(timeoutCh <-chan time.Time) bool {
 	return w.WatchCtx(ctx) == context.Canceled
 }
 
-// WatchCtx is used to wait for any channel of the watch set to trigger or for the
-// context to be cancelled. Watch with a timeout channel can be mimicked by
-// creating a context with a deadline. WatchCtx should be preferred over Watch.
+// WatchCtx blocks until one of the channels in the watch set is closed, or
+// ctx is done (cancelled or exceeds the deadline). WatchCtx returns an error
+// if the ctx causes it to unblock, otherwise returns nil.
+//
+// WatchCtx should be preferred over Watch.
 func (w WatchSet) WatchCtx(ctx context.Context) error {
 	if w == nil {
 		return nil