Make generic registry easier to understand

pkg/genericapiserver/registry/generic/registry/storage_factory.go

@@ -25,6 +25,8 @@ import (
 	"k8s.io/kubernetes/pkg/storage/storagebackend/factory"
 )
 
+var _ generic.StorageDecorator = StorageWithCacher
+
 // Creates a cacher based given storageConfig.
 func StorageWithCacher(
 	storageConfig *storagebackend.Config,

pkg/genericapiserver/registry/generic/storage_decorator.go

@@ -24,8 +24,8 @@ import (
 	"k8s.io/kubernetes/pkg/storage/storagebackend/factory"
 )
 
-// StorageDecorator is a function signature for producing
-// a storage.Interface from given parameters.
+// StorageDecorator is a function signature for producing a storage.Interface
+// and an associated DestroyFunc from given parameters.
 type StorageDecorator func(
 	config *storagebackend.Config,
 	capacity int,
@@ -36,7 +36,8 @@ type StorageDecorator func(
 	getAttrsFunc storage.AttrFunc,
 	trigger storage.TriggerPublisherFunc) (storage.Interface, factory.DestroyFunc)
 
-// Returns given 'storageInterface' without any decoration.
+// UndecoratedStorage returns the given a new storage from the given config
+// without any decoration.
 func UndecoratedStorage(
 	config *storagebackend.Config,
 	capacity int,

pkg/genericapiserver/registry/rest/create.go

@@ -34,7 +34,7 @@ import (
 // API conventions.
 type RESTCreateStrategy interface {
 	runtime.ObjectTyper
-	// The name generate is used when the standard GenerateName field is set.
+	// The name generator is used when the standard GenerateName field is set.
 	// The NameGenerator will be invoked prior to validation.
 	names.NameGenerator
 
@@ -45,11 +45,16 @@ type RESTCreateStrategy interface {
 	// sort order-insensitive list fields, etc.  This should not remove fields
 	// whose presence would be considered a validation error.
 	PrepareForCreate(ctx genericapirequest.Context, obj runtime.Object)
-	// Validate is invoked after default fields in the object have been filled in before
-	// the object is persisted.  This method should not mutate the object.
+	// Validate returns an ErrorList with validation errors or nil.  Validate
+	// is invoked after default fields in the object have been filled in
+	// before the object is persisted.  This method should not mutate the
+	// object.
 	Validate(ctx genericapirequest.Context, obj runtime.Object) field.ErrorList
-	// Canonicalize is invoked after validation has succeeded but before the
-	// object has been persisted.  This method may mutate the object.
+	// Canonicalize allows an object to be mutated into a canonical form. This
+	// ensures that code that operates on these objects can rely on the common
+	// form for things like comparison.  Canonicalize is invoked after
+	// validation has succeeded but before the object has been persisted.
+	// This method may mutate the object.
 	Canonicalize(obj runtime.Object)
 }
 

pkg/genericapiserver/registry/rest/export.go

@@ -21,7 +21,11 @@ import (
 	genericapirequest "k8s.io/apiserver/pkg/endpoints/request"
 )
 
-// RESTExportStrategy is the interface that defines how to export a Kubernetes object
+// RESTExportStrategy is the interface that defines how to export a Kubernetes
+// object.  An exported object is stripped of non-user-settable fields and
+// optionally, the identifying information related to the object's identity in
+// the cluster so that it can be loaded into a different namespace or entirely
+// different cluster without conflict.
 type RESTExportStrategy interface {
 	// Export strips fields that can not be set by the user.  If 'exact' is false
 	// fields specific to the cluster are also stripped

pkg/genericapiserver/registry/rest/meta.go

@@ -35,7 +35,10 @@ func FillObjectMetaSystemFields(ctx genericapirequest.Context, meta *metav1.Obje
 	meta.SelfLink = ""
 }
 
-// ValidNamespace returns false if the namespace on the context differs from the resource.  If the resource has no namespace, it is set to the value in the context.
+// ValidNamespace returns false if the namespace on the context differs from
+// the resource.  If the resource has no namespace, it is set to the value in
+// the context.
+//
 // TODO(sttts): move into pkg/genericapiserver/endpoints
 func ValidNamespace(ctx genericapirequest.Context, resource *metav1.ObjectMeta) bool {
 	ns, ok := genericapirequest.NamespaceFrom(ctx)

pkg/genericapiserver/registry/rest/update.go

@@ -48,8 +48,11 @@ type RESTUpdateStrategy interface {
 	// filled in before the object is persisted.  This method should not mutate
 	// the object.
 	ValidateUpdate(ctx genericapirequest.Context, obj, old runtime.Object) field.ErrorList
-	// Canonicalize is invoked after validation has succeeded but before the
-	// object has been persisted.  This method may mutate the object.
+	// Canonicalize allows an object to be mutated into a canonical form. This
+	// ensures that code that operates on these objects can rely on the common
+	// form for things like comparison.  Canonicalize is invoked after
+	// validation has succeeded but before the object has been persisted.
+	// This method may mutate the object.
 	Canonicalize(obj runtime.Object)
 	// AllowUnconditionalUpdate returns true if the object can be updated
 	// unconditionally (irrespective of the latest resource version), when

pkg/storage/cacher.go

@@ -188,9 +188,9 @@ type Cacher struct {
 	stopWg   sync.WaitGroup
 }
 
-// Create a new Cacher responsible from service WATCH and LIST requests from its
-// internal cache and updating its cache in the background based on the given
-// configuration.
+// Create a new Cacher responsible for servicing WATCH and LIST requests from
+// its internal cache and updating its cache in the background based on the
+// given configuration.
 func NewCacherFromConfig(config CacherConfig) *Cacher {
 	watchCache := newWatchCache(config.CacheCapacity, config.KeyFunc, config.GetAttrsFunc)
 	listerWatcher := newCacherListerWatcher(config.Storage, config.ResourcePrefix, config.NewListFunc)