📖 Add more docs to SyncPeriod

SyncPeriod is likely to get ignored if you use a predicate.

This PR updates the docs to make this more obvious.

Author: guettli

pkg/cache/cache.go

@@ -42,9 +42,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client/apiutil"
 )
 
-var (
-	defaultSyncPeriod = 10 * time.Hour
-)
+var defaultSyncPeriod = 10 * time.Hour
 
 // InformerGetOptions defines the behavior of how informers are retrieved.
 type InformerGetOptions internal.GetOptions
@@ -172,6 +170,18 @@ type Options struct {
 	// is "done" with an object, and would otherwise not requeue it, i.e., we
 	// recommend the `Reconcile` function return `reconcile.Result{RequeueAfter: t}`,
 	// instead of `reconcile.Result{}`.
+	//
+	// SyncPeriod will trigger update events with the old object being equal to the new
+	// object. Excep the cache was out of sync.
+	// If you filter update events like this:
+	// Controller.Watch(
+	//     &source.Kind{Type: v1.MyCustomKind},
+	//     &handler.EnqueueRequestForObject{},
+	//     predicate.Or(predicate.GenerationChangedPredicate{},
+	//         predicate.LabelChangedPredicate{}))
+	// then the SyncPeriod will not trigger a Reconcile call, because the update event
+	// will be ignored by the predicate.
+
 	SyncPeriod *time.Duration
 
 	// ReaderFailOnMissingInformer configures the cache to return a ErrResourceNotCached error when a user