📚 Add function docs

utils/slice.go

@@ -19,6 +19,14 @@ func Contains[T comparable](slice []T, item T) bool {
 	return false
 }
 
+// RandomValueCycle returns a function that cycles through the provided slice of values
+// in a random order. Each call to the returned function will yield a value from the slice.
+// The order of values is determined by the provided random number generator.
+//
+// The returned function will cycle through the values in a random order until all values
+// have been returned at least once. After all values have been returned, the function will
+// reset and start cycling through the values in a random order again.
+// The returned function isn't thread-safe and should be used in a single-threaded context.
 func RandomValueCycle[Value any](values []Value, localRand *rand.Rand) func() Value {
 	var (
 		clientsCount int = len(values)