Improve clarity around BatchKeyFn function usage

README.md

@@ -317,7 +317,7 @@ IDs each:
 IDs can often be fetched from multiple data sources. Hence, we'll want to
 prefix the ID in order to make the cache key unique. The package provides more
 functionality for this that we'll see later on, but for now we'll use the most
-simple version which adds a string prefix to every ID:
+simple version which adds a string prefix together with a seperator to every ID:
 
 ```go
 	keyPrefixFn := cacheClient.BatchKeyFn("my-data-source")
@@ -803,11 +803,12 @@ func NewAPI(c *sturdyc.Client[string]) *API {
 }
 
 func (a *API) GetBatch(ctx context.Context, ids []string) (map[string]string, error) {
-	// We are going to use a cache a key function that prefixes each id.
+	// We are going to pass the cache a key function that prefixes each id with the provided prefix and "-ID-".
 	// This makes it possible to save the same id for different data sources.
 	cacheKeyFn := a.BatchKeyFn("some-prefix")
 
 	// The fetchFn is only going to retrieve the IDs that are not in the cache.
+	// The cacheMisses will contain the missing IDs and not the formatted keys.
 	fetchFn := func(_ context.Context, cacheMisses []string) (map[string]string, error) {
 		log.Printf("Cache miss. Fetching ids: %s\n", strings.Join(cacheMisses, ", "))
 		// Batch functions should return a map where the key is the id of the record.

examples/basic/main.go

@@ -60,8 +60,8 @@ func demonstrateGetOrFetchBatch(cacheClient *sturdyc.Client[int]) {
 		{"11", "12", "13", "14", "15"},
 	}
 
-	// We'll use a cache key function to add a prefix to the IDs. If we only used
-	// the IDs, we wouldn't be able to fetch the same IDs from multiple data sources.
+	// We are going use a cache key function that prefixes each id with the provided prefix and "-ID-".
+	// If we only used the IDs, we wouldn't be able to fetch the same IDs from multiple data sources.
 	keyPrefixFn := cacheClient.BatchKeyFn("my-data-source")
 
 	// Request the keys  for each batch.

examples/batch/main.go

@@ -20,11 +20,12 @@ func NewAPI(c *sturdyc.Client[string]) *API {
 }
 
 func (a *API) GetBatch(ctx context.Context, ids []string) (map[string]string, error) {
-	// We are going to pass the cache a key function that prefixes each id.
+	// We are going to pass the cache a key function that prefixes each id with the provided prefix and "-ID-".
 	// This makes it possible to save the same id for different data sources.
 	cacheKeyFn := a.BatchKeyFn("some-prefix")
 
 	// The fetchFn is only going to retrieve the IDs that are not in the cache.
+	// The cacheMisses will contain the missing IDs and not the formatted keys.
 	fetchFn := func(_ context.Context, cacheMisses []string) (map[string]string, error) {
 		log.Printf("Cache miss. Fetching ids: %s\n", strings.Join(cacheMisses, ", "))
 		// Batch functions should return a map where the key is the id of the record.

examples/buffering/main.go

@@ -23,7 +23,7 @@ func NewOrderAPI(client *sturdyc.Client[string]) *OrderAPI {
 }
 
 func (a *OrderAPI) OrderStatus(ctx context.Context, ids []string, opts OrderOptions) (map[string]string, error) {
-	// We use the  PermutedBatchKeyFn when an ID isn't enough to uniquely identify a
+	// We use the PermutedBatchKeyFn when an ID isn't enough to uniquely identify a
 	// record. The cache is going to store each id once per set of options. In a more
 	// realistic scenario, the opts would be query params or arguments to a DB query.
 	cacheKeyFn := a.PermutatedBatchKeyFn("key", opts)

examples/permutations/main.go

@@ -23,7 +23,7 @@ func NewOrderAPI(c *sturdyc.Client[string]) *OrderAPI {
 }
 
 func (a *OrderAPI) OrderStatus(ctx context.Context, ids []string, opts OrderOptions) (map[string]string, error) {
-	// We use the  PermutedBatchKeyFn when an ID isn't enough to uniquely identify a
+	// We use the PermutedBatchKeyFn when an ID isn't enough to uniquely identify a
 	// record. The cache is going to store each id once per set of options. In a more
 	// realistic scenario, the opts would be query params or arguments to a DB query.
 	cacheKeyFn := a.PermutatedBatchKeyFn("key", opts)

keys.go

@@ -158,16 +158,16 @@ func (c *Client[T]) PermutatedKey(prefix string, permutationStruct interface{})
 }
 
 // BatchKeyFn provides a function that can be used in conjunction with
-// "GetOrFetchBatch". It takes in a prefix and returns a function that will
-// append the ID as a suffix for each item.
+// "GetOrFetchBatch". It takes in a prefix and returns a function that will format
+// a string with the prefix and id seperated by "-ID-" for each item.
 //
 // Parameters:
 //
 //	prefix - The prefix to be used for each cache key.
 //
 // Returns:
 //
-//	A function that takes an ID and returns a cache key string with the given prefix and ID.
+//	A function that takes an ID and returns a cache key string with the given prefix and ID seperated by "-ID-".
 func (c *Client[T]) BatchKeyFn(prefix string) KeyFn {
 	return func(id string) string {
 		return fmt.Sprintf("%s-ID-%s", prefix, id)
@@ -189,7 +189,7 @@ func (c *Client[T]) BatchKeyFn(prefix string) KeyFn {
 //
 // Returns:
 //
-//	A function that takes an ID and returns a cache key string with the given prefix, permutation struct fields, and ID.
+//	A function that takes an ID and returns a cache key string with the given prefix and permutation struct fields followed by "-ID-" and the ID.
 func (c *Client[T]) PermutatedBatchKeyFn(prefix string, permutationStruct interface{}) KeyFn {
 	return func(id string) string {
 		key := c.PermutatedKey(prefix, permutationStruct)