📖 Improve docs for manager.Options.SyncPeriod (kubernetes-sigs#1232)

* Improve docs for manager.Options.SyncPeriod

The comment tries to capture more of the thoughts exchanged in
kubernetes-sigs#88.

* Note that  SyncPeriod applies to all controllers.

Co-authored-by: Joe Julian <me@joejulian.name>

* Make explanation of SyncPeriod more precise..

Co-authored-by: Joe Julian <me@joejulian.name>

Co-authored-by: Joe Julian <me@joejulian.name>

pkg/manager/manager.go

@@ -111,6 +111,25 @@ type Options struct {
 	// value only if you know what you are doing. Defaults to 10 hours if unset.
 	// there will a 10 percent jitter between the SyncPeriod of all controllers
 	// so that all controllers will not send list requests simultaneously.
+	//
+	// This applies to all controllers.
+	//
+	// A period sync happens for two reasons:
+	// 1. To insure against a bug in the controller that causes an object to not
+	// be requeued, when it otherwise should be requeued.
+	// 2. To insure against an unknown bug in controller-runtime, or its dependencies,
+	// that causes an object to not be requeued, when it otherwise should be
+	// requeued, or to be removed from the queue, when it otherwise should not
+	// be removed.
+	//
+	// If you want
+	// 1. to insure against missed watch events, or
+	// 2. to poll services that cannot be watched,
+	// then we recommend that, instead of changing the default period, the
+	// controller requeue, with a constant duration `t`, whenever the controller
+	// 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 *time.Duration
 
 	// Logger is the logger that should be used by this manager.