Merge pull request #125472 from karlkfi/karl-watch-comments

Add details to watch interface method comments

Kubernetes-commit: b498eb97406f780fbbeb39204f50bc473e64af56

go.mod

@@ -26,7 +26,7 @@ require (
 	google.golang.org/protobuf v1.33.0
 	gopkg.in/evanphx/json-patch.v4 v4.12.0
 	k8s.io/api v0.0.0-20240611003639-590e50434bf1
-	k8s.io/apimachinery v0.0.0-20240611003333-1a6a62ad18e9
+	k8s.io/apimachinery v0.0.0-20240613101152-30b7bf11450a
 	k8s.io/klog/v2 v2.120.1
 	k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340
 	k8s.io/utils v0.0.0-20230726121419-3b25d923346b

go.sum

@@ -159,8 +159,8 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 k8s.io/api v0.0.0-20240611003639-590e50434bf1 h1:oxDdCGF5j63Mpb6Des2N1CCsNubC8scZdBm1DRAkwRM=
 k8s.io/api v0.0.0-20240611003639-590e50434bf1/go.mod h1:5Cjw9MqZjRGElVN/sncIVEj4uQqmgd5uRSkUupucc3U=
-k8s.io/apimachinery v0.0.0-20240611003333-1a6a62ad18e9 h1:uEYcGyr07zLyUWoDL38erRxiSRNnusAK211luE2Lb/c=
-k8s.io/apimachinery v0.0.0-20240611003333-1a6a62ad18e9/go.mod h1:3nAExNh3CrzC6eKT9a32j/rv+uJ8Zod87oOmgUjZNAY=
+k8s.io/apimachinery v0.0.0-20240613101152-30b7bf11450a h1:CS/axI7Kd2PJvIwtGyWqDFCTB++MXTCgXGQEYmAkqyo=
+k8s.io/apimachinery v0.0.0-20240613101152-30b7bf11450a/go.mod h1:3nAExNh3CrzC6eKT9a32j/rv+uJ8Zod87oOmgUjZNAY=
 k8s.io/klog/v2 v2.120.1 h1:QXU6cPEOIslTGvZaXvFWiP9VKyeet3sawzTOvdXb4Vw=
 k8s.io/klog/v2 v2.120.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
 k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 h1:BZqlfIlq5YbRMFko6/PM7FjZpUb45WallggurYhKGag=

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)
 }