From c68732b80820f2c18887a39a2fc6951f55e94de4 Mon Sep 17 00:00:00 2001
From: Mike Spreitzer <mspreitz@us.ibm.com>
Date: Tue, 7 Jan 2020 02:23:29 -0500
Subject: [PATCH] finished pass over comments on Controller, and commented
 sharedIndexInformer

Kubernetes-commit: f2a8e2d9c9cadc8a969efa1d4edef833ff701e2f
---
 tools/cache/controller.go      | 14 +++++++++++++-
 tools/cache/shared_informer.go | 17 +++++++++++++++--
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/tools/cache/controller.go b/tools/cache/controller.go
index 4efa8f90..a9cd24ef 100644
--- a/tools/cache/controller.go
+++ b/tools/cache/controller.go
@@ -87,10 +87,22 @@ type controller struct {
 	clock          clock.Clock
 }
 
-// Controller is a low-level controller used in sharedIndexInformer.
+// Controller is a low-level controller that is parameterized by a
+// Config and used in sharedIndexInformer.
 type Controller interface {
+	// Run does two things.  One is to construct and run a Reflector
+	// to pump objects/notifications from the Config's ListerWatcher
+	// to the Config's Queue and possibly invoke the occasional Resync
+	// on that Queue.  The other is to repeatedly Pop from the Queue
+	// and process with the Config's ProcessFunc.  Both of these
+	// continue until `stopCh` is closed.
 	Run(stopCh <-chan struct{})
+
+	// HasSynced delegates to the Queue
 	HasSynced() bool
+
+	// LastSyncResourceVersion delegates to the Reflector when there
+	// is one, otherwise returns the empty string
 	LastSyncResourceVersion() string
 }
 
diff --git a/tools/cache/shared_informer.go b/tools/cache/shared_informer.go
index ba7a00ad..2f687ce8 100644
--- a/tools/cache/shared_informer.go
+++ b/tools/cache/shared_informer.go
@@ -144,7 +144,7 @@ type SharedInformer interface {
 	AddEventHandlerWithResyncPeriod(handler ResourceEventHandler, resyncPeriod time.Duration)
 	// GetStore returns the informer's local cache as a Store.
 	GetStore() Store
-	// GetController gives back a synthetic interface that "votes" to start the informer
+	// GetController is deprecated, it does nothing useful
 	GetController() Controller
 	// Run starts and runs the shared informer, returning after it stops.
 	// The informer will be stopped when stopCh is closed.
@@ -237,6 +237,19 @@ func WaitForCacheSync(stopCh <-chan struct{}, cacheSyncs ...InformerSynced) bool
 	return true
 }
 
+// `*sharedIndexInformer` implements SharedIndexInformer and has three
+// main components.  One is an indexed local cache, `indexer Indexer`.
+// The second main component is a Controller that pulls
+// objects/notifications using the ListerWatcher and pushes them into
+// a DeltaFIFO --- whose knownObjects is the informer's local cache
+// --- while concurrently Popping Deltas values from that fifo and
+// processing them with `sharedIndexInformer::HandleDeltas`.  Each
+// invocation of HandleDeltas, which is done with the fifo's lock
+// held, processes each Delta in turn.  For each Delta this both
+// updates the local cache and stuffs the relevant notification into
+// the sharedProcessor.  The third main component is that
+// sharedProcessor, which is responsible for relaying those
+// notifications to each of the informer's clients.
 type sharedIndexInformer struct {
 	indexer    Indexer
 	controller Controller
@@ -250,7 +263,7 @@ type sharedIndexInformer struct {
 	// expected to handle.  Only the type needs to be right, except
 	// that when that is `unstructured.Unstructured` the object's
 	// `"apiVersion"` must also be right.
-	objectType    runtime.Object
+	objectType runtime.Object
 
 	// resyncCheckPeriod is how often we want the reflector's resync timer to fire so it can call
 	// shouldResync to check if any of our listeners need a resync.