From cd90c3ddf3f06320e34c75d39244588282f4f94a Mon Sep 17 00:00:00 2001
From: Winni Neessen <wn@neessen.net>
Date: Sun, 6 Oct 2024 17:00:49 +0200
Subject: [PATCH] Update randNum function and documentation for multiple
 versions

Expanded randNum function comments to provide detailed behavior and usage across different Go versions. Enhanced the randomStringSecure function doc to explain its cryptographic secure implementation and error handling.
---
 random.go     | 29 ++++++++++++++++++++++++-----
 random_119.go | 12 +++++++++++-
 random_121.go | 12 +++++++++++-
 random_122.go | 12 ++++++++++--
 4 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/random.go b/random.go
index 3a3f16b..2478c75 100644
--- a/random.go
+++ b/random.go
@@ -14,14 +14,33 @@ import (
 const cr = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
 
 // Bitmask sizes for the string generators (based on 93 chars total)
+//
+// These constants define bitmask-related values used for efficient random string generation.
+// The bitmask operates over 93 possible characters, and the constants help determine the
+// number of bits and indices used in the process.
 const (
-	letterIdxBits = 7                    // 7 bits to represent a letter index
-	letterIdxMask = 1<<letterIdxBits - 1 // All 1-bits, as many as letterIdxBits
-	letterIdxMax  = 63 / letterIdxBits   // # of letter indices fitting in 63 bits
+	// letterIdxBits: Number of bits (7) needed to represent a letter index.
+	letterIdxBits = 7
+	// letterIdxMask: Bitmask to extract letter indices (all 1-bits for letterIdxBits).
+	letterIdxMask = 1<<letterIdxBits - 1
+	// letterIdxMax: The maximum number of letter indices that fit in 63 bits.
+	letterIdxMax = 63 / letterIdxBits
 )
 
-// randomStringSecure returns a random, string of length characters. This method uses the
-// crypto/random package and therfore is cryptographically secure
+// randomStringSecure returns a random string of the specified length.
+//
+// This function generates a cryptographically secure random string of the given length using
+// the crypto/rand package. It ensures that the randomness is secure and suitable for
+// cryptographic purposes. The function reads random bytes, converts them to indices within
+// a character range, and builds the string. If an error occurs while reading from the random
+// pool, it returns the error.
+//
+// Parameters:
+//   - length: The length of the random string to be generated.
+//
+// Returns:
+//   - A randomly generated string.
+//   - An error if the random generation fails.
 func randomStringSecure(length int) (string, error) {
 	randString := strings.Builder{}
 	randString.Grow(length)
diff --git a/random_119.go b/random_119.go
index 4b45c55..98d761c 100644
--- a/random_119.go
+++ b/random_119.go
@@ -12,7 +12,17 @@ import (
 	"time"
 )
 
-// randNum returns a random number with a maximum value of length
+// randNum returns a random number with a maximum value of maxval.
+//
+// This function generates a random integer between 0 and maxval (exclusive). It seeds the
+// random number generator with the current time in nanoseconds to ensure different results
+// each time the function is called.
+//
+// Parameters:
+//   - maxval: The upper bound for the random number generation (exclusive).
+//
+// Returns:
+//   - A random integer between 0 and maxval. If maxval is less than or equal to 0, it returns 0.
 func randNum(maxval int) int {
 	if maxval <= 0 {
 		return 0
diff --git a/random_121.go b/random_121.go
index b401bc8..ea1e399 100644
--- a/random_121.go
+++ b/random_121.go
@@ -11,7 +11,17 @@ import (
 	"math/rand"
 )
 
-// randNum returns a random number with a maximum value of length
+// randNum returns a random number with a maximum value of maxval.
+//
+// This function generates a random integer between 0 and maxval (exclusive). If maxval is less
+// than or equal to 0, it returns 0. The random number generator uses the default seed provided
+// by the rand package.
+//
+// Parameters:
+//   - maxval: The upper bound for the random number generation (exclusive).
+//
+// Returns:
+//   - A random integer between 0 and maxval. If maxval is less than or equal to 0, it returns 0.
 func randNum(maxval int) int {
 	if maxval <= 0 {
 		return 0
diff --git a/random_122.go b/random_122.go
index 9a6132b..27ded3d 100644
--- a/random_122.go
+++ b/random_122.go
@@ -12,8 +12,16 @@ import (
 )
 
 // randNum returns a random number with a maximum value of maxval.
-// go-mail compiled with Go 1.22+ will make use of the novel math/rand/v2 interface
-// Older versions of Go will use math/rand
+//
+// This function generates a random integer between 0 and maxval (exclusive). It utilizes
+// the math/rand/v2 interface for Go 1.22+ and will default to math/rand for older Go versions.
+// If maxval is less than or equal to 0, it returns 0.
+//
+// Parameters:
+//   - maxval: The upper bound for the random number generation (exclusive).
+//
+// Returns:
+//   - A random integer between 0 and maxval. If maxval is less than or equal to 0, it returns 0.
 func randNum(maxval int) int {
 	if maxval <= 0 {
 		return 0