doc: improve and reference existing bug in the code (#356)

internal/randx/randx.go

@@ -1,4 +1,6 @@
-// Package randx contains math/rand extensions.
+// Package randx contains math/rand extensions. The functions
+// exported by this package do not use a CSRNG so you SHOULD NOT
+// use these strings for, e.g., generating passwords.
 package randx
 
 import (
@@ -25,18 +27,23 @@ func lettersWithString(n int, letterBytes string) string {
 	return string(b)
 }
 
-// Letters return a string composed of random letters.
+// Letters return a string composed of random letters. Note that
+// this function uses a non-cryptographically-secure generator.
 func Letters(n int) string {
 	return lettersWithString(n, letters)
 }
 
-// LettersUppercase return a string composed of random uppercase letters.
+// LettersUppercase return a string composed of random uppercase
+// letters. Note that this function uses a non-cryptographically-secure
+// generator. So, we SHOULD NOT use it for generating passwords.
 func LettersUppercase(n int) string {
 	return lettersWithString(n, uppercase)
 }
 
 // ChangeCapitalization returns a new string where the capitalization
-// of each character is changed at random.
+// of each character is changed at random. Note that this function
+// uses a non-cryptographically-secure generator. So, we SHOULD NOT use
+// it for generating passwords.
 func ChangeCapitalization(source string) (dest string) {
 	rnd := rand.New(rand.NewSource(time.Now().UnixNano()))
 	for _, chr := range source {