Tweak docs

Author: newpavlov

README.md

@@ -19,7 +19,7 @@ library like [`rand`].
 
 [`rand`]: https://crates.io/crates/rand
 
-## Usage
+## Examples
 
 Add the `getrandom` dependency to your `Cargo.toml` file:
 
@@ -38,6 +38,16 @@ fn get_random_u128() -> Result<u128, getrandom::Error> {
 }
 ```
 
+The crate also support direct generation of random `u32` and `u64` values:
+
+```rust
+fn get_rand_u32_u64() -> Result<(u32, u64), getrandom::Error> {
+    let a = getrandom::u32()?;
+    let b = getrandom::u64()?;
+    Ok((a, b))
+}
+```
+
 ## Supported targets
 
 | Target             | Target Triple      | Implementation
@@ -106,6 +116,25 @@ WILL NOT have any effect on its downstream users.
 
 [`.cargo/config.toml`]: https://doc.rust-lang.org/cargo/reference/config.html
 
+### "Insecure" functions
+
+Sometimes, early in the boot process, the OS has not collected enough
+entropy to securely seed its RNG. This is especially common on virtual
+machines, where standard "random" events are hard to come by.
+
+Some operating system interfaces always block until the RNG is securely
+seeded, which can take anywhere from a few seconds to more than a minute.
+Some platforms offer a choice between blocking and getting potentially less
+secure randomness, i.e. generated data may be less difficult for an attacker
+to predict.
+
+We expose this functionality through two sets of functions. The "secure"
+functions ([`fill`], [`fill_uninit`], [`u32`], and [`u64`]) may block but
+always return "secure" randomness suitable for cryptographic needs.
+Meanwhile, their "insecure" counterparts ([`insecure_fill`],
+[`insecure_fill_uninit`], [`insecure_u32`], and [`insecure_u64`]) may return
+randomness of lesser quality but are less likely to block in entropy-starved scenarios.
+
 ### WebAssembly support
 
 This crate fully supports the [WASI] and [Emscripten] targets. However,
@@ -210,31 +239,6 @@ The fallback can be disabled by enabling the `linux_getrandom` opt-in backend.
 Note that doing so will bump minimum supported Linux kernel version to 3.17
 and Android API level to 23 (Marshmallow).
 
-### Early boot
-
-Sometimes, early in the boot process, the OS has not collected enough
-entropy to securely seed its RNG. This is especially common on virtual
-machines, where standard "random" events are hard to come by.
-
-Some operating system interfaces always block until the RNG is securely
-seeded. This can take anywhere from a few seconds to more than a minute.
-A few (Linux, NetBSD and Solaris) offer a choice between blocking and
-getting an error; in these cases, we always choose to block.
-
-On Linux (when the `getrandom` system call is not available), reading from
-`/dev/urandom` never blocks, even when the OS hasn't collected enough
-entropy yet. To avoid returning low-entropy bytes, we first poll
-`/dev/random` and only switch to `/dev/urandom` once this has succeeded.
-
-On OpenBSD, this kind of entropy accounting isn't available, and on
-NetBSD, blocking on it is discouraged. On these platforms, nonblocking
-interfaces are used, even when reliable entropy may not be available.
-On the platforms where it is used, the reliability of entropy accounting
-itself isn't free from controversy. This library provides randomness
-sourced according to the platform's best practices, but each platform has
-its own limits on the grade of randomness it can promise in environments
-with few sources of entropy.
-
 ## Error handling
 
 We always prioritize failure over returning known insecure "random" bytes.
@@ -346,4 +350,11 @@ dual licensed as above, without any additional terms or conditions.
 [LICENSE-MIT]: https://github.com/rust-random/getrandom/blob/master/LICENSE-MIT
 
 [`Error::UNEXPECTED`]: https://docs.rs/getrandom/latest/getrandom/struct.Error.html#associatedconstant.UNEXPECTED
+[`fill`]: https://docs.rs/getrandom/latest/getrandom/fn.fill.html
 [`fill_uninit`]: https://docs.rs/getrandom/latest/getrandom/fn.fill_uninit.html
+[`u32`]: https://docs.rs/getrandom/latest/getrandom/fn.u32.html
+[`u64`]: https://docs.rs/getrandom/latest/getrandom/fn.u64.html
+[`insecure_fill`]: https://docs.rs/getrandom/latest/getrandom/fn.insecure_fill.html
+[`insecure_fill_uninit`]: https://docs.rs/getrandom/latest/getrandom/fn.insecure_fill_uninit.html
+[`insecure_u32`]: https://docs.rs/getrandom/latest/getrandom/fn.insecure_u32.html
+[`insecure_u64`]: https://docs.rs/getrandom/latest/getrandom/fn.insecure_u64.html

src/lib.rs

@@ -1,6 +1,13 @@
 // Overwrite links to crate items with intra-crate links
 //! [`Error::UNEXPECTED`]: Error::UNEXPECTED
+//! [`fill`]: fill
 //! [`fill_uninit`]: fill_uninit
+//! [`u32`]: u32()
+//! [`u64`]: u64()
+//! [`insecure_fill`]: insecure_fill
+//! [`insecure_fill_uninit`]: insecure_fill_uninit
+//! [`insecure_u32`]: insecure_u32
+//! [`insecure_u64`]: insecure_u64
 
 #![no_std]
 #![doc(
@@ -74,6 +81,8 @@ pub fn fill(dst: &mut [u8]) -> Result<(), Error> {
 
 /// Fill `dst` with **potentially insecure** random bytes from the system's entropy source.
 ///
+/// See the ["insecure" functions][crate#insecure-functions] section for more information.
+///
 /// # Examples
 /// ```
 /// # fn main() -> Result<(), getrandom::Error> {
@@ -132,6 +141,8 @@ pub fn fill_uninit(dst: &mut [MaybeUninit<u8>]) -> Result<&mut [u8], Error> {
 /// No part of `dst` will ever be de-initialized at any point, regardless
 /// of what is returned.
 ///
+/// See the ["insecure" functions][crate#insecure-functions] section for more information.
+///
 /// # Examples
 /// ```ignore
 /// # // We ignore this test since `uninit_array` is unstable.
@@ -167,6 +178,8 @@ pub fn u32() -> Result<u32, Error> {
 
 /// Get **potentially insecure** random `u32` from the system's entropy source.
 ///
+/// See the ["insecure" functions][crate#insecure-functions] section for more information.
+///
 /// # Examples
 /// ```
 /// # fn main() -> Result<(), getrandom::Error> {
@@ -193,6 +206,8 @@ pub fn u64() -> Result<u64, Error> {
 
 /// Get **potentially insecure** random `u64` from the system's entropy source.
 ///
+/// See the ["insecure" functions][crate#insecure-functions] section for more information.
+///
 /// # Examples
 /// ```
 /// # fn main() -> Result<(), getrandom::Error> {