docs: fix comments

Signed-off-by: Rueian <[email protected]>

Author: rueian

binary.go

@@ -7,8 +7,8 @@ import (
 	"unsafe"
 )
 
-// BinaryString convert the provided []byte into a string without copy. It does what strings.Builder.String() does.
-// Redis Strings are binary safe, this means that it is safe to store any []byte into Redis directly.
+// BinaryString convert the provided []byte into a string without a copy. It does what strings.Builder.String() does.
+// Redis Strings are binary safe; this means that it is safe to store any []byte into Redis directly.
 // Users can use this BinaryString helper to insert a []byte as the part of redis command. For example:
 //
 //	client.B().Set().Key(rueidis.BinaryString([]byte{0})).Value(rueidis.BinaryString([]byte{0})).Build()

cache.go

@@ -20,7 +20,7 @@ type CacheStoreOption struct {
 // More detailed interface requirement can be found in cache_test.go
 type CacheStore interface {
 	// Flight is called when DoCache and DoMultiCache, with the requested client side ttl and the current time.
-	// It should look up the store in single-flight manner and return one of the following three combinations:
+	// It should look up the store in a single-flight manner and return one of the following three combinations:
 	// Case 1: (empty RedisMessage, nil CacheEntry)     <- when cache missed, and rueidis will send the request to redis.
 	// Case 2: (empty RedisMessage, non-nil CacheEntry) <- when cache missed, and rueidis will use CacheEntry.Wait to wait for response.
 	// Case 3: (non-empty RedisMessage, nil CacheEntry) <- when cache hit
@@ -33,15 +33,15 @@ type CacheStore interface {
 	// It should not only deliver the error to all CacheEntry.Wait but also remove the CacheEntry from the store.
 	Cancel(key, cmd string, err error)
 	// Delete is called when receiving invalidation notifications from redis.
-	// If the keys is nil then it should delete all non-pending cached entries under all keys.
-	// If the keys is not nil then it should delete all non-pending cached entries under those keys.
+	// If the keys are nil, then it should delete all non-pending cached entries under all keys.
+	// If the keys are not nil, then it should delete all non-pending cached entries under those keys.
 	Delete(keys []RedisMessage)
-	// Close is called when connection between redis is broken.
+	// Close is called when the connection between redis is broken.
 	// It should flush all cached entries and deliver the error to all pending CacheEntry.Wait.
 	Close(err error)
 }
 
-// CacheEntry should be used to wait for single-flight response when cache missed.
+// CacheEntry should be used to wait for a single-flight response when cache missed.
 type CacheEntry interface {
 	Wait(ctx context.Context) (RedisMessage, error)
 }

client.go

@@ -59,7 +59,7 @@ retry:
 			}
 		}
 	}
-	if resp.NonRedisError() == nil { // not recycle cmds if error, since cmds may be used later in pipe. consider recycle them by pipe
+	if resp.NonRedisError() == nil { // not recycle cmds if error, since cmds may be used later in the pipe.
 		cmds.PutCompleted(cmd)
 	}
 	return resp
@@ -93,7 +93,7 @@ retry:
 		var ml []Completed
 	recover:
 		ml = ml[:0]
-		var txIdx int // check transaction block, if zero then not in transaction
+		var txIdx int // check transaction block, if zero, then not in transaction
 		for i, resp := range resps {
 			if resp.NonRedisError() == errConnExpired {
 				if txIdx > 0 {
@@ -103,7 +103,7 @@ retry:
 				}
 				break
 			}
-			// if no error then check if transaction block
+			// if no error, then check if transaction block
 			if isMulti(multi[i]) {
 				txIdx = i
 			} else if isExec(multi[i]) {

cluster.go

@@ -14,7 +14,7 @@ import (
 	"github.com/redis/rueidis/internal/util"
 )
 
-// ErrNoSlot indicates that there is no redis node owns the key slot.
+// ErrNoSlot indicates that there is no redis node owning the key slot.
 var ErrNoSlot = errors.New("the slot has no redis node")
 var ErrReplicaOnlyConflict = errors.New("ReplicaOnly conflicts with SendToReplicas option")
 var ErrInvalidShardsRefreshInterval = errors.New("ShardsRefreshInterval must be greater than or equal to 0")
@@ -117,7 +117,7 @@ func (c *clusterClient) init() error {
 			if err := cc.Dial(); err == nil {
 				c.mu.Lock()
 				if _, ok := c.conns[addr]; ok {
-					go cc.Close() // abort the new connection instead of closing the old one which may already been used
+					go cc.Close() // abort the new connection instead of closing the old one, which may already been used
 				} else {
 					c.conns[addr] = connrole{
 						conn: cc,
@@ -502,7 +502,7 @@ func (c *clusterClient) B() Builder {
 }
 
 func (c *clusterClient) Do(ctx context.Context, cmd Completed) (resp RedisResult) {
-	if resp = c.do(ctx, cmd); resp.NonRedisError() == nil { // not recycle cmds if error, since cmds may be used later in pipe. consider recycle them by pipe
+	if resp = c.do(ctx, cmd); resp.NonRedisError() == nil { // not recycle cmds if error, since cmds may be used later in the pipe.
 		cmds.PutCompleted(cmd)
 	}
 	return resp
@@ -600,7 +600,7 @@ func (c *clusterClient) _pickMulti(multi []Completed) (retries *connretry, init
 			} else {
 				cc = c.pslots[cmd.Slot()]
 			}
-			if cc == nil { // check cc == nil again in case of non-deterministic SendToReplicas.
+			if cc == nil { // check cc == nil again in the case of non-deterministic SendToReplicas.
 				return nil, false
 			}
 			re := retries.m[cc]
@@ -774,7 +774,7 @@ func (c *clusterClient) doretry(
 			var ml []Completed
 		recover:
 			ml = ml[:0]
-			var txIdx int // check transaction block, if zero then not in transaction
+			var txIdx int // check transaction block, if zero, then not in transaction
 			for i, resp := range resps.s {
 				if resp.NonRedisError() == errConnExpired {
 					if txIdx > 0 {
@@ -784,7 +784,7 @@ func (c *clusterClient) doretry(
 					}
 					break
 				}
-				// if no error then check if transaction block
+				// if no error, then check if transaction block
 				if isMulti(re.commands[i]) {
 					txIdx = i
 				} else if isExec(re.commands[i]) {
@@ -830,7 +830,7 @@ func (c *clusterClient) DoMulti(ctx context.Context, multi ...Completed) []Redis
 	attempts := 1
 
 retry:
-	retries.RetryDelay = -1 // Assume no retry. Because client retry flag can be set to false.
+	retries.RetryDelay = -1 // Assume no retry. Because a client retry flag can be set to false.
 
 	var cc1 conn
 	var re1 *retry
@@ -1184,7 +1184,7 @@ func (c *clusterClient) DoMultiCache(ctx context.Context, multi ...CacheableTTL)
 	attempts := 1
 
 retry:
-	retries.RetryDelay = -1 // Assume no retry. Because client retry flag can be set to false.
+	retries.RetryDelay = -1 // Assume no retry. Because a client retry flag can be set to false.
 
 	var cc1 conn
 	var re1 *retrycache

cmds.go

@@ -5,7 +5,7 @@ import "github.com/redis/rueidis/internal/cmds"
 // Builder represents a command builder. It should only be created from the client.B() method.
 type Builder = cmds.Builder
 
-// Incomplete represents an incomplete Redis command. It should then be completed by calling the Build().
+// Incomplete represents an incomplete Redis command. It should then be completed by calling Build().
 type Incomplete = cmds.Incomplete
 
 // Completed represents a completed Redis command. It should only be created from the Build() of a command builder.

helper.go

@@ -8,7 +8,7 @@ import (
 	intl "github.com/redis/rueidis/internal/cmds"
 )
 
-// MGetCache is a helper that consults the client-side caches with multiple keys by grouping keys within same slot into multiple GETs
+// MGetCache is a helper that consults the client-side caches with multiple keys by grouping keys within the same slot into multiple GETs
 func MGetCache(client Client, ctx context.Context, ttl time.Duration, keys []string) (ret map[string]RedisMessage, err error) {
 	if len(keys) == 0 {
 		return make(map[string]RedisMessage), nil
@@ -38,7 +38,7 @@ func isCacheDisabled(client Client) bool {
 	return false
 }
 
-// MGet is a helper that consults the redis directly with multiple keys by grouping keys within same slot into MGET or multiple GETs
+// MGet is a helper that consults the redis directly with multiple keys by grouping keys within the same slot into MGET or multiple GETs
 func MGet(client Client, ctx context.Context, keys []string) (ret map[string]RedisMessage, err error) {
 	if len(keys) == 0 {
 		return make(map[string]RedisMessage), nil
@@ -57,7 +57,7 @@ func MGet(client Client, ctx context.Context, keys []string) (ret map[string]Red
 	return doMultiGet(client, ctx, cmds.s, keys)
 }
 
-// MSet is a helper that consults the redis directly with multiple keys by grouping keys within same slot into MSETs or multiple SETs
+// MSet is a helper that consults the redis directly with multiple keys by grouping keys within the same slot into MSETs or multiple SETs
 func MSet(client Client, ctx context.Context, kvs map[string]string) map[string]error {
 	if len(kvs) == 0 {
 		return make(map[string]error)
@@ -76,7 +76,7 @@ func MSet(client Client, ctx context.Context, kvs map[string]string) map[string]
 	return doMultiSet(client, ctx, cmds.s)
 }
 
-// MDel is a helper that consults the redis directly with multiple keys by grouping keys within same slot into DELs
+// MDel is a helper that consults the redis directly with multiple keys by grouping keys within the same slot into DELs
 func MDel(client Client, ctx context.Context, keys []string) map[string]error {
 	if len(keys) == 0 {
 		return make(map[string]error)
@@ -95,7 +95,7 @@ func MDel(client Client, ctx context.Context, keys []string) map[string]error {
 	return doMultiSet(client, ctx, cmds.s)
 }
 
-// MSetNX is a helper that consults the redis directly with multiple keys by grouping keys within same slot into MSETNXs or multiple SETNXs
+// MSetNX is a helper that consults the redis directly with multiple keys by grouping keys within the same slot into MSETNXs or multiple SETNXs
 func MSetNX(client Client, ctx context.Context, kvs map[string]string) map[string]error {
 	if len(kvs) == 0 {
 		return make(map[string]error)
@@ -114,7 +114,7 @@ func MSetNX(client Client, ctx context.Context, kvs map[string]string) map[strin
 	return doMultiSet(client, ctx, cmds.s)
 }
 
-// JsonMGetCache is a helper that consults the client-side caches with multiple keys by grouping keys within same slot into multiple JSON.GETs
+// JsonMGetCache is a helper that consults the client-side caches with multiple keys by grouping keys within the same slot into multiple JSON.GETs
 func JsonMGetCache(client Client, ctx context.Context, ttl time.Duration, keys []string, path string) (ret map[string]RedisMessage, err error) {
 	if len(keys) == 0 {
 		return make(map[string]RedisMessage), nil
@@ -127,7 +127,7 @@ func JsonMGetCache(client Client, ctx context.Context, ttl time.Duration, keys [
 	return doMultiCache(client, ctx, cmds.s, keys)
 }
 
-// JsonMGet is a helper that consults redis directly with multiple keys by grouping keys within same slot into JSON.MGETs or multiple JSON.GETs
+// JsonMGet is a helper that consults redis directly with multiple keys by grouping keys within the same slot into JSON.MGETs or multiple JSON.GETs
 func JsonMGet(client Client, ctx context.Context, keys []string, path string) (ret map[string]RedisMessage, err error) {
 	if len(keys) == 0 {
 		return make(map[string]RedisMessage), nil
@@ -146,7 +146,7 @@ func JsonMGet(client Client, ctx context.Context, keys []string, path string) (r
 	return doMultiGet(client, ctx, cmds.s, keys)
 }
 
-// JsonMSet is a helper that consults redis directly with multiple keys by grouping keys within same slot into JSON.MSETs or multiple JOSN.SETs
+// JsonMSet is a helper that consults redis directly with multiple keys by grouping keys within the same slot into JSON.MSETs or multiple JOSN.SETs
 func JsonMSet(client Client, ctx context.Context, kvs map[string]string, path string) map[string]error {
 	if len(kvs) == 0 {
 		return make(map[string]error)
@@ -165,7 +165,7 @@ func JsonMSet(client Client, ctx context.Context, kvs map[string]string, path st
 	return doMultiSet(client, ctx, cmds.s)
 }
 
-// DecodeSliceOfJSON is a helper that struct-scans each RedisMessage into dest, which must be a slice of pointer.
+// DecodeSliceOfJSON is a helper that struct-scans each RedisMessage into dest, which must be a slice of the pointer.
 func DecodeSliceOfJSON[T any](result RedisResult, dest *[]T) error {
 	values, err := result.ToArray()
 	if err != nil {

internal/cmds/cmds.go

@@ -97,7 +97,7 @@ func ToBlock(c *Completed) {
 	c.cf |= blockTag
 }
 
-// Incomplete represents an incomplete Redis command. It should then be completed by calling the Build().
+// Incomplete represents an incomplete Redis command. It should then be completed by calling Build().
 type Incomplete struct {
 	cs *CommandSlice
 	cf int16 // use int16 instead of uint16 to make a difference with Completed

lua.go

@@ -22,15 +22,15 @@ func NewLuaScriptReadOnly(script string) *Lua {
 
 // NewLuaScriptNoSha creates a Lua instance whose Lua.Exec uses EVAL.
 // Sha1 is not calculated, SCRIPT LOAD is not used, no EVALSHA is used.
-// The main motivation is to be FIPS compliant, also avoid tiny chance of SHA-1 collisions.
+// The main motivation is to be FIPS compliant, also avoid the tiny chance of SHA-1 collisions.
 // This comes with a performance cost as the script is sent to a server every time.
 func NewLuaScriptNoSha(script string) *Lua {
 	return newLuaScript(script, false, true)
 }
 
 // NewLuaScriptReadOnlyNoSha creates a Lua instance whose Lua.Exec uses EVAL_RO.
 // Sha1 is not calculated, SCRIPT LOAD is not used, no EVALSHA_RO is used.
-// The main motivation is to be FIPS compliant, also avoid tiny chance of SHA-1 collisions.
+// The main motivation is to be FIPS compliant, also avoid the tiny chance of SHA-1 collisions.
 // This comes with a performance cost as the script is sent to a server every time.
 func NewLuaScriptReadOnlyNoSha(script string) *Lua {
 	return newLuaScript(script, true, true)
@@ -62,9 +62,9 @@ type Lua struct {
 }
 
 // Exec the script to the given Client.
-// It will first try with the EVALSHA/EVALSHA_RO and then EVAL/EVAL_RO if first try failed.
-// If Lua is initialized with disabled SHA1, it will use EVAL/EVAL_RO without EVALSHA/EVALSHA_RO attempt.
-// Cross slot keys are prohibited if the Client is a cluster client.
+// It will first try with the EVALSHA/EVALSHA_RO and then EVAL/EVAL_RO if the first try failed.
+// If Lua is initialized with disabled SHA1, it will use EVAL/EVAL_RO without the EVALSHA/EVALSHA_RO attempt.
+// Cross-slot keys are prohibited if the Client is a cluster client.
 func (s *Lua) Exec(ctx context.Context, c Client, keys, args []string) (resp RedisResult) {
 	var isNoScript bool
 	if !s.nosha1 {
@@ -95,7 +95,7 @@ type LuaExec struct {
 // ExecMulti exec the script multiple times by the provided LuaExec to the given Client.
 // It will first try SCRIPT LOAD the script to all redis nodes and then exec it with the EVALSHA/EVALSHA_RO.
 // If Lua is initialized with disabled SHA1, it will use EVAL/EVAL_RO and no script loading.
-// Cross slot keys within single LuaExec are prohibited if the Client is a cluster client.
+// Cross-slot keys within the single LuaExec are prohibited if the Client is a cluster client.
 func (s *Lua) ExecMulti(ctx context.Context, c Client, multi ...LuaExec) (resp []RedisResult) {
 	if !s.nosha1 {
 		var e atomic.Value