rand: document all functions, document range notation form, fix copy-pasta (#7619)

vlib/rand/rand.v

@@ -7,13 +7,14 @@ import rand.util
 import rand.wyrand
 import time
 
-// Configuration struct for creating a new instance of the default RNG.
+// PRNGConfigStruct is a configuration struct for creating a new instance of the default RNG.
 pub struct PRNGConfigStruct {
 	seed []u32 = util.time_seed_array(2)
 }
 
 __global ( default_rng &wyrand.WyRandRNG )
 
+// init initializes the default RNG.
 fn init() {
 	default_rng = new_default({})
 }
@@ -30,103 +31,103 @@ pub fn seed(seed []u32) {
 	default_rng.seed(seed)
 }
 
-// u32() returns a uniformly distributed u32 in _[0, 2<sup>32</sup>)_
+// u32 returns a uniformly distributed `u32` in range `[0, 2³²)`.
 pub fn u32() u32 {
 	return default_rng.u32()
 }
 
-// u64() returns a uniformly distributed u64 in _[0, 2<sup>64</sup>)_
+// u64 returns a uniformly distributed `u64` in range `[0, 2⁶⁴)`.
 pub fn u64() u64 {
 	return default_rng.u64()
 }
 
-// u32n(max) returns a uniformly distributed pseudorandom 32-bit signed positive u32 in _[0, max)_
+// u32n returns a uniformly distributed pseudorandom 32-bit signed positive `u32` in range `[0, max)`.
 pub fn u32n(max u32) u32 {
 	return default_rng.u32n(max)
 }
 
-// u64n(max) returns a uniformly distributed pseudorandom 64-bit signed positive u64 in _[0, max)_
+// u64n returns a uniformly distributed pseudorandom 64-bit signed positive `u64` in range `[0, max)`.
 pub fn u64n(max u64) u64 {
 	return default_rng.u64n(max)
 }
 
-// u32_in_range(min, max) returns a uniformly distributed pseudorandom 32-bit unsigned u32 in _[min, max)_
+// u32_in_range returns a uniformly distributed pseudorandom 32-bit unsigned `u32` in range `[min, max)`.
 pub fn u32_in_range(min u32, max u32) u32 {
 	return default_rng.u32_in_range(min, max)
 }
 
-// u64_in_range(min, max) returns a uniformly distributed pseudorandom 64-bit unsigned u64 in _[min, max)_
+// u64_in_range returns a uniformly distributed pseudorandom 64-bit unsigned `u64` in range `[min, max)`.
 pub fn u64_in_range(min u64, max u64) u64 {
 	return default_rng.u64_in_range(min, max)
 }
 
-// int() returns a uniformly distributed pseudorandom 32-bit signed (possibly negative) int
+// int returns a uniformly distributed pseudorandom 32-bit signed (possibly negative) `int`.
 pub fn int() int {
 	return default_rng.int()
 }
 
-// intn(max) returns a uniformly distributed pseudorandom 32-bit signed positive int in _[0, max)_
+// intn returns a uniformly distributed pseudorandom 32-bit signed positive `int` in range `[0, max)`.
 pub fn intn(max int) int {
 	return default_rng.intn(max)
 }
 
-// int_in_range(min, max) returns a uniformly distributed pseudorandom
-// 32-bit signed int in [min, max). Both min and max can be negative, but we must have _min < max_.
+// int_in_range returns a uniformly distributed pseudorandom  32-bit signed int in range `[min, max)`.
+// Both `min` and `max` can be negative, but we must have `min < max`.
 pub fn int_in_range(min int, max int) int {
 	return default_rng.int_in_range(min, max)
 }
 
-// int31() returns a uniformly distributed pseudorandom 31-bit signed positive int
+// int31 returns a uniformly distributed pseudorandom 31-bit signed positive `int`.
 pub fn int31() int {
 	return default_rng.int31()
 }
 
-// i64() returns a uniformly distributed pseudorandom 64-bit signed (possibly negative) i64
+// i64 returns a uniformly distributed pseudorandom 64-bit signed (possibly negative) `i64`.
 pub fn i64() i64 {
 	return default_rng.i64()
 }
 
-// i64n(max) returns a uniformly distributed pseudorandom 64-bit signed positive i64 in _[0, max)_
+// i64n returns a uniformly distributed pseudorandom 64-bit signed positive `i64` in range `[0, max)`.
 pub fn i64n(max i64) i64 {
 	return default_rng.i64n(max)
 }
 
-// i64_in_range(min, max) returns a uniformly distributed pseudorandom 64-bit signed int in _[min, max)_
+// i64_in_range returns a uniformly distributed pseudorandom 64-bit signed `i64` in range `[min, max)`.
 pub fn i64_in_range(min i64, max i64) i64 {
 	return default_rng.i64_in_range(min, max)
 }
 
-// int63() returns a uniformly distributed pseudorandom 63-bit signed positive int
+// int63 returns a uniformly distributed pseudorandom 63-bit signed positive `i64`.
 pub fn int63() i64 {
 	return default_rng.int63()
 }
 
-// f32() returns a uniformly distributed 32-bit floating point in _[0, 1)_
+// f32 returns a uniformly distributed 32-bit floating point in range `[0, 1)`.
 pub fn f32() f32 {
 	return default_rng.f32()
 }
 
-// f64() returns a uniformly distributed 64-bit floating point in _[0, 1)_
+// f64 returns a uniformly distributed 64-bit floating point in range `[0, 1)`.
 pub fn f64() f64 {
 	return default_rng.f64()
 }
 
-// f32n() returns a uniformly distributed 32-bit floating point in _[0, max)_
+// f32n returns a uniformly distributed 32-bit floating point in range `[0, max)`.
 pub fn f32n(max f32) f32 {
 	return default_rng.f32n(max)
 }
 
-// f64n() returns a uniformly distributed 64-bit floating point in _[0, max)_
+// f64n returns a uniformly distributed 64-bit floating point in range `[0, max)`.
 pub fn f64n(max f64) f64 {
 	return default_rng.f64n(max)
 }
 
-// f32_in_range(min, max) returns a uniformly distributed 32-bit floating point in _[min, max)_
+// f32_in_range returns a uniformly distributed 32-bit floating point in range `[min, max)`.
 pub fn f32_in_range(min f32, max f32) f32 {
 	return default_rng.f32_in_range(min, max)
 }
 
-// f64_in_range(min, max) returns a uniformly distributed 64-bit floating point in _[min, max)_
+// f64_in_range returns a uniformly distributed 64-bit floating point in range `[min, max)`.
 pub fn f64_in_range(min f64, max f64) f64 {
 	return default_rng.f64_in_range(min, max)
 }
@@ -135,6 +136,7 @@ const (
 	chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
 )
 
+// string returns a string of length `len` containing random characters in range `[a-zA-Z]`.
 pub fn string(len int) string {
 	mut buf := malloc(len)
 	for i in 0 .. len {
@@ -145,7 +147,7 @@ pub fn string(len int) string {
 	return unsafe {buf.vstring_with_len(len)}
 }
 
-// rand.uuid_v4 generate a completely random UUID (v4)
+// uuid_v4 generates a random (v4) UUID
 // See https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
 pub fn uuid_v4() string {
 	buflen := 36
@@ -189,7 +191,7 @@ const (
 	ulid_encoding = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
 )
 
-// rand.ulid generates an Unique Lexicographically sortable IDentifier.
+// ulid generates an Unique Lexicographically sortable IDentifier.
 // See https://github.com/ulid/spec .
 // NB: ULIDs can leak timing information, if you make them public, because
 // you can infer the rate at which some resource is being created, like
@@ -199,6 +201,7 @@ pub fn ulid() string {
 	return ulid_at_millisecond(time.utc().unix_time_milli())
 }
 
+// ulid_at_millisecond does the same as `ulid` but takes a custom Unix millisecond timestamp via `unix_time_milli`.
 pub fn ulid_at_millisecond(unix_time_milli u64) string {
 	buflen := 26
 	mut buf := malloc(27)