Made the comment on SharedInformer give a complete description

This comment formerly contained only a contrast with "standard
informer", but there is no longer such a thing so the comment lacked
much important information.

Kubernetes-commit: 121e4741463043eac188bb4eed51f07122262d69

tools/cache/shared_informer.go

@@ -31,31 +31,83 @@ import (
 	"k8s.io/klog"
 )
 
-// SharedInformer has a shared data cache and is capable of distributing notifications for changes
-// to the cache to multiple listeners who registered via AddEventHandler. If you use this, there is
-// one behavior change compared to a standard Informer.  When you receive a notification, the cache
-// will be AT LEAST as fresh as the notification, but it MAY be more fresh.  You should NOT depend
-// on the contents of the cache exactly matching the notification you've received in handler
-// functions.  If there was a create, followed by a delete, the cache may NOT have your item.  This
-// has advantages over the broadcaster since it allows us to share a common cache across many
-// controllers. Extending the broadcaster would have required us keep duplicate caches for each
-// watch.
+// SharedInformer provides eventually consistent linkage of its
+// clients to the authoritative state of a given collection of
+// objects.  An object is identified by its API group, kind/resource,
+// namespace, and name.  One SharedInfomer provides linkage to objects
+// of a particular API group and kind/resource.  The linked object
+// collection of a SharedInformer may be further restricted to one
+// namespace and/or by label selector and/or field selector.
+//
+// The authoritative state of an object is what apiservers provide
+// access to, and an object goes through a strict sequence of states.
+// A state is either "absent" or present with a ResourceVersion and
+// other appropriate content.
+//
+// A SharedInformer maintains a local cache, exposed by Store(), of
+// the state of each relevant object.  This cache is eventually
+// consistent with the authoritative state.  This means that, unless
+// prevented by persistent communication problems, if ever a
+// particular object ID X is authoritatively associated with a state S
+// then for every SharedInformer I whose collection includes (X, S)
+// eventually either (1) I's cache associates X with S or a later
+// state of X, (2) I is stopped, or (3) the authoritative state
+// service for X terminates.  To be formally complete, we say that the
+// absent state meets any restriction by label selector or field
+// selector.
+//
+// As a simple example, if a collection of objects is henceforeth
+// unchanging and a SharedInformer is created that links to that
+// collection then that SharedInformer's cache eventually holds an
+// exact copy of that collection (unless it is stopped too soon, the
+// authoritative state service ends, or communication problems between
+// the two persistently thwart achievement).
+//
+// As another simple example, if the local cache ever holds a
+// non-absent state for some object ID and the object is eventually
+// removed from the authoritative state then eventually the object is
+// removed from the local cache (unless the SharedInformer is stopped
+// too soon, the authoritative state service emnds, or communication
+// problems persistently thwart the desired result).
+//
+// The keys in Store() are of the form namespace/name for namespaced
+// objects, and are simply the name for non-namespaced objects.
+//
+// A client is identified here by a ResourceEventHandler.  For every
+// update to the SharedInformer's local cache and for every client,
+// eventually either the SharedInformer is stopped or the client is
+// notified of the update.  These notifications happen after the
+// corresponding cache update and, in the case of a
+// SharedIndexInformer, after the corresponding index updates.  It is
+// possible that additional cache and index updates happen before such
+// a prescribed notification.  For a given SharedInformer and client,
+// all notifications are delivered sequentially.  For a given
+// SharedInformer, client, and object ID, the notifications are
+// delivered in order.
+//
+// A delete notification exposes the last locally known non-absent
+// state, except that its ResourceVersion is replaced with a
+// ResourceVersion in which the object is actually absent.
 type SharedInformer interface {
 	// AddEventHandler adds an event handler to the shared informer using the shared informer's resync
 	// period.  Events to a single handler are delivered sequentially, but there is no coordination
 	// between different handlers.
 	AddEventHandler(handler ResourceEventHandler)
-	// AddEventHandlerWithResyncPeriod adds an event handler to the shared informer using the
-	// specified resync period.  Events to a single handler are delivered sequentially, but there is
-	// no coordination between different handlers.
+	// AddEventHandlerWithResyncPeriod adds an event handler to the
+	// shared informer using the specified resync period.  The resync
+	// operation consists of delivering to the handler a create
+	// notification for every object in the informer's local cache; it
+	// does not add any interactions with the authoritative storage.
 	AddEventHandlerWithResyncPeriod(handler ResourceEventHandler, resyncPeriod time.Duration)
-	// GetStore returns the Store.
+	// 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() Controller
 	// Run starts the shared informer, which will be stopped when stopCh is closed.
 	Run(stopCh <-chan struct{})
-	// HasSynced returns true if the shared informer's store has synced.
+	// HasSynced returns true if the shared informer's store has been
+	// informed by at least one full LIST of the authoritative state
+	// of the informer's object collection.  This is unrelated to "resync".
 	HasSynced() bool
 	// LastSyncResourceVersion is the resource version observed when last synced with the underlying
 	// store. The value returned is not synchronized with access to the underlying store and is not