From 4160909495626262ae514bab30fe81a3ff869d39 Mon Sep 17 00:00:00 2001 From: Mike Spreitzer Date: Wed, 26 Jun 2019 00:03:15 -0400 Subject: [PATCH] Fixed and clarified comments and parameter names in index.go (#77633) * Fixed and clarified comments and parameter names in index.go Fixed the comment on IndexFunc to say that it returns multiple indexed values. Clarified the comments and parameter names in the Indexer interface to consistently use a dichotomy between "storage keys" and "indexed values". * Updated comments in index.go based on review by Liggitt --- .../src/k8s.io/client-go/tools/cache/index.go | 26 +++++++++++++------ 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/staging/src/k8s.io/client-go/tools/cache/index.go b/staging/src/k8s.io/client-go/tools/cache/index.go index 15acb168ef2..2a4bcbc47d6 100644 --- a/staging/src/k8s.io/client-go/tools/cache/index.go +++ b/staging/src/k8s.io/client-go/tools/cache/index.go @@ -23,17 +23,27 @@ import ( "k8s.io/apimachinery/pkg/util/sets" ) -// Indexer is a storage interface that lets you list objects using multiple indexing functions +// Indexer is a storage interface that lets you list objects using multiple indexing functions. +// There are three kinds of strings here. +// One is a storage key, as defined in the Store interface. +// Another kind is a name of an index. +// The third kind of string is an "indexed value", which is produced by an +// IndexFunc and can be a field value or any other string computed from the object. type Indexer interface { Store - // Retrieve list of objects that match on the named indexing function + // Index returns the stored objects whose set of indexed values + // intersects the set of indexed values of the given object, for + // the named index Index(indexName string, obj interface{}) ([]interface{}, error) - // IndexKeys returns the set of keys that match on the named indexing function. - IndexKeys(indexName, indexKey string) ([]string, error) - // ListIndexFuncValues returns the list of generated values of an Index func + // IndexKeys returns the storage keys of the stored objects whose + // set of indexed values for the named index includes the given + // indexed value + IndexKeys(indexName, indexedValue string) ([]string, error) + // ListIndexFuncValues returns all the indexed values of the given index ListIndexFuncValues(indexName string) []string - // ByIndex lists object that match on the named indexing function with the exact key - ByIndex(indexName, indexKey string) ([]interface{}, error) + // ByIndex returns the stored objects whose set of indexed values + // for the named index includes the given indexed value + ByIndex(indexName, indexedValue string) ([]interface{}, error) // GetIndexer return the indexers GetIndexers() Indexers @@ -42,7 +52,7 @@ type Indexer interface { AddIndexers(newIndexers Indexers) error } -// IndexFunc knows how to provide an indexed value for an object. +// IndexFunc knows how to compute the set of indexed values for an object. type IndexFunc func(obj interface{}) ([]string, error) // IndexFuncToKeyFuncAdapter adapts an indexFunc to a keyFunc. This is only useful if your index function returns