Add details to watch interface method comments

The watch.Interface design is hard to change, because it would break
most client-go users that perform watches. So instead of changing the
interface to be more user friendly, this change updates the method
comments to explain the different responsibilities of the consumer
(client user) and the producer (interface implementer).

Kubernetes-commit: 1f35231a1d4f7b8586a7ec589c799729eeb4f7c4

tools/cache/listwatch.go

@@ -36,6 +36,10 @@ type Lister interface {
 // Watcher is any object that knows how to start a watch on a resource.
 type Watcher interface {
 	// Watch should begin a watch at the specified version.
+	//
+	// If Watch returns an error, it should handle its own cleanup, including
+	// but not limited to calling Stop() on the watch, if one was constructed.
+	// This allows the caller to ignore the watch, if the error is non-nil.
 	Watch(options metav1.ListOptions) (watch.Interface, error)
 }