Improve documentation for Random::Secure

src/random/secure.cr

@@ -1,14 +1,16 @@
 require "crystal/system/random"
 
-# `Random::Secure` provides a [cryptographically secure pseudorandom number generator (CSRPNG)](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator)
-# for cryptography and secure usages such as generating secret keys, or seeding a pseudorandom number generator (PRNG).
+# `Random::Secure` generates random numbers from a secure source provided by the system.
+#
+# It uses a [cryptographically secure pseudorandom number generator (CSRPNG)](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator)
+# for cryptography and secure usages such as generating secret keys, or seeding
+# a pseudorandom number generator (PRNG).
 #
 # ```
 # Random::Secure.rand(6)            # => 4
 # [1, 5, 6].shuffle(Random::Secure) # => [6, 1, 5]
 # ```
 #
-# It uses a secure source provided by the operating system.
 # On OpenBSD, it uses [`arc4random`](https://man.openbsd.org/arc4random),
 # on Linux [`getrandom`](http://man7.org/linux/man-pages/man2/getrandom.2.html) (if the kernel supports it),
 # on Windows [`RtlGenRandom`](https://docs.microsoft.com/en-us/windows/win32/api/ntsecapi/nf-ntsecapi-rtlgenrandom),
@@ -17,15 +19,19 @@ require "crystal/system/random"
 # For generating *high quality* random numbers, a pseudorandom number generator
 # (PRNG) such as `Random::PCG32` should be used instead, or preferably one with
 # more state (e.g. `xoshiro256**`). These number generators are much faster
-# than `Random::Secure`.
+# than `Random::Secure` and suitable for many use cases with lower
+# cryptographic security demands. The values generated by pseudorandom number
+# generators are easier to predict. When this could be exploited, it's better
+# to use `Random::Secure`.
 module Random::Secure
   extend Random
+  extend self
 
-  def self.next_u
+  def next_u
     Crystal::System::Random.next_u
   end
 
-  def self.random_bytes(buf : Bytes)
+  def random_bytes(buf : Bytes)
     Crystal::System::Random.random_bytes(buf)
   end