Improve comment formatting and update usage

bench/permutations.go

@@ -1,16 +1,14 @@
 package bench
 
-// A PermutationGenerator provides a way to pass integer IDs through a permutation
+// PermutationGenerator provides a way to pass integer IDs through a permutation
 // map that is pseudorandom but repeatable. This could be done with rand.Perm,
 // but that would require storing a [Iterations]int64 array, which we want to avoid
 // for large values of Iterations.
 // It works by using a Linear Congruence Generator (https://en.wikipedia.org/wiki/Linear_congruential_generator)
-// with modulus = Iterations,
+// with modulus m = Iterations,
 // c = an arbitrary prime,
 // a = computed to ensure the full period.
-
 // relevant stackoverflow: http://cs.stackexchange.com/questions/29822/lazily-computing-a-random-permutation-of-the-positive-integers
-
 type PermutationGenerator struct {
 	a int64
 	c int64
@@ -29,12 +27,12 @@ func (p *PermutationGenerator) Next(n int64) int64 {
 	return (n*p.a + p.c) % p.m
 }
 
+// LCG parameters must satisfy three conditions:
+// 1. m and c are relatively prime (satisfied for prime c != m)
+// 2. a-1 is divisible by all prime factors of m
+// 3. a-1 is divisible by 4 if m is divisible by 4
+// Additionally, a seed can be used to select between different permutations
 func LCGmultiplierFromModulus(m int64, seed int64) int64 {
-	// LCG parameters must satisfy three conditions:
-	// 1. m and c are relatively prime (satisfied for prime c != m)
-	// 2. a-1 is divisible by all prime factors of m
-	// 3. a-1 is divisible by 4 if m is divisible by 4
-	// Additionally, a seed can be used to select between different permutations
 	factors := primeFactors(m)
 	product := int64(1)
 	for p := range factors {

bench/zipf.go

@@ -13,10 +13,7 @@ import (
 )
 
 // ZipfSetBits sets random bits according to the Zipf-Mandelbrot distribution.
-// This distribution accepts two parameters for both bitmaps and profiles:
-// Exponent in (1, inf), default 1.001 - "sharpness" of the distribution.
-// Ratio in (0, 1), default 0.25 - maximum variation of the distribution (the relative probability of the least likely ID to the most likely ID)
-//
+// This distribution accepts two parameters, Exponent and Ratio, for both bitmaps and profiles.
 // It also uses PermutationGenerator to permute IDs randomly.
 type ZipfSetBits struct {
 	HasClient
@@ -41,7 +38,12 @@ type ZipfSetBits struct {
 
 func (b *ZipfSetBits) Usage() string {
 	return `
-zipf-set-bits sets random bits according to Zipf distribution
+zipf-set-bits sets random bits according to the Zipf distribution.
+This is a power-law distribution controlled by two parameters.
+Exponent, in the range (1, inf), with a default value of 1.001, controls
+the "sharpness" of the distribution, with higher exponent being sharper.
+Ratio, in the range (0, 1), with a default value of 0.25, controls the
+maximum variation of the distribution, with higher ratio being more uniform.
 
 Usage: zipf-set-bits [arguments]
 

cmd/pilosactl/main.go

@@ -1210,7 +1210,7 @@ The following arguments are available:
 	subcommands:
 		diagonal-set-bits
 		random-set-bits
-    zipf-set-bits
+		zipf-set-bits
 		multi-db-set-bits
 		random-query
 		import