Further tweaking up the wording

Hopfully improving, based on wojtek's review.

Kubernetes-commit: 59807be5abe6a96aad715823b7bab9fbd5d837bd

tools/cache/controller.go

@@ -51,7 +51,7 @@ type Config struct {
 	// ObjectType is an example object of the type this controller is
 	// 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.
+	// `"apiVersion"` and `"kind"` must also be right.
 	ObjectType runtime.Object
 
 	// FullResyncPeriod is the period at which ShouldResync is considered.
@@ -98,7 +98,7 @@ type Controller interface {
 	// continue until `stopCh` is closed.
 	Run(stopCh <-chan struct{})
 
-	// HasSynced delegates to the Queue
+	// HasSynced delegates to the Config's Queue
 	HasSynced() bool
 
 	// LastSyncResourceVersion delegates to the Reflector when there

tools/cache/delta_fifo.go

@@ -67,15 +67,18 @@ func NewDeltaFIFO(keyFunc KeyFunc, knownObjects KeyListerGetter) *DeltaFIFO {
 	return f
 }
 
-// DeltaFIFO is like FIFO, but allows the PopProcessFunc to process
+// DeltaFIFO is like FIFO, but differs in two ways.  One is that the
-// deletes and adds Sync to the ways an object can be applied to an
+// accumulator associated with a given object's key is not that object
-// acumulator.  The accumulator associated with a given object's key
+// but rather a Deltas, which is a slice of Delta values for that
-// is a Deltas, which is a slice of Delta values for that object.
+// object.  Applying an object to a Deltas means to append a Delta
-// Applying an object to a Deltas means to append a Delta except when
+// except when the potentially appended Delta is a Deleted and the
-// the potentially appended Delta is a Deleted and the Deltas already
+// Deltas already ends with a Deleted.  In that case the Deltas does
-// ends with a Deleted.  In that case the Deltas does not grow,
+// not grow, although the terminal Deleted will be replaced by the new
-// although the terminal Deleted will be replaced by the new Deleted if
+// Deleted if the older Deleted's object is a
-// the older Deleted's object is a DeletedFinalStateUnknown.
+// DeletedFinalStateUnknown.
+//
+// The other difference is that DeltaFIFO has an additional way that
+// an object can be applied to an accumulator, called Sync.
 //
 // DeltaFIFO is a producer-consumer queue, where a Reflector is
 // intended to be the producer, and the consumer is whatever calls

tools/cache/reflector.go

@@ -57,8 +57,8 @@ type Reflector struct {
 	expectedTypeName string
 	// An example object of the type we expect to place in the store.
 	// Only the type needs to be right, except that when that is
-	// `unstructured.Unstructured` the object's `"apiVersion"` must
+	// `unstructured.Unstructured` the object's `"apiVersion"` and
-	// also be right.
+	// `"kind"` must also be right.
 	expectedType reflect.Type
 	// The GVK of the object we expect to place in the store if unstructured.
 	expectedGVK *schema.GroupVersionKind

tools/cache/shared_informer.go

@@ -262,7 +262,7 @@ type sharedIndexInformer struct {
 	// objectType is an example object of the type this informer is
 	// 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.
+	// `"apiVersion"` and `"kind"` must also be right.
 	objectType runtime.Object
 
 	// resyncCheckPeriod is how often we want the reflector's resync timer to fire so it can call
@@ -503,11 +503,11 @@ func (s *sharedIndexInformer) HandleDeltas(obj interface{}) error {
 }
 
 // sharedProcessor has a collection of processorListener and can
-// distribute a notification object to its listeners.  Each distribute
+// distribute a notification object to its listeners.  There are two
-// operation is `sync` or not.  The sync distributions go to a subset
+// kinds of distribute operations.  The sync distributions go to a
-// of the listeners that (a) is recomputed in the occasional calls to
+// subset of the listeners that (a) is recomputed in the occasional
-// shouldResync and (b) every listener is initially put in.  The
+// calls to shouldResync and (b) every listener is initially put in.
-// non-sync distributions go to every listener.
+// The non-sync distributions go to every listener.
 type sharedProcessor struct {
 	listenersStarted bool
 	listenersLock    sync.RWMutex