Merge pull request #648 from ericchiang/dev-storage-docs

storage: update godocs

storage/kubernetes/doc.go

-// Package kubernetes provides a storage interface using Kubernetes third party APIs.
+// Package kubernetes provides a storage implementation using Kubernetes third party APIs.
 package kubernetes

storage/storage.go

@@ -78,9 +78,20 @@ type Storage interface {
 	DeleteRefresh(id string) error
 	DeletePassword(email string) error
 
-	// Update functions are assumed to be a performed within a single object transaction.
+	// Update methods take a function for updating an object then performs that update within
+	// a transaction. "updater" functions may be called multiple times by a single update call.
+	//
+	// Because new fields may be added to resources, updaters should only modify existing
+	// fields on the old object rather then creating new structs. For example:
+	//
+	//		updater := func(old storage.Client) (storage.Client, error) {
+	//			old.Secret = newSecret
+	//			return old, nil
+	//		}
+	//		if err := s.UpdateClient(clientID, updater); err != nil {
+	//			// update failed, handle error
+	//		}
 	//
-	// updaters may be called multiple times.
 	UpdateClient(id string, updater func(old Client) (Client, error)) error
 	UpdateKeys(updater func(old Keys) (Keys, error)) error
 	UpdateAuthRequest(id string, updater func(a AuthRequest) (AuthRequest, error)) error