From cf527e9ba4288bac9236ffe4046234438d998214 Mon Sep 17 00:00:00 2001
From: Diggory Hardy <git@dhardy.name>
Date: Tue, 7 May 2019 09:57:43 +0100
Subject: [PATCH] Update features doc

---
 Cargo.toml |  8 ++++++--
 README.md  | 60 +++++++++++++++++++++++-------------------------------
 2 files changed, 32 insertions(+), 36 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 280d39d148f..a8479c905f3 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -20,17 +20,21 @@ travis-ci = { repository = "rust-random/rand" }
 appveyor = { repository = "rust-random/rand" }
 
 [features]
+# Meta-features:
 default = ["std"] # without "std" rand uses libcore
 nightly = ["simd_support"] # enables all features requiring nightly rust
+
+# Optional dependencies:
 std = ["rand_core/std", "alloc", "getrandom"]
 alloc = ["rand_core/alloc"]  # enables Vec and Box support (without std)
-i128_support = [] # enables i128 and u128 support
-simd_support = ["packed_simd"] # enables SIMD support
 serde1 = ["rand_core/serde1", "rand_isaac/serde1", "rand_xorshift/serde1"] # enables serialization for PRNGs
 # re-export optional WASM dependencies to avoid breakage:
 wasm-bindgen = ["getrandom/wasm-bindgen"]
 stdweb = ["getrandom/stdweb"]
 
+# Configuration:
+simd_support = ["packed_simd"] # enables SIMD support
+
 [workspace]
 members = [
     "rand_core",
diff --git a/README.md b/README.md
index 244df867736..ca2283cdb40 100644
--- a/README.md
+++ b/README.md
@@ -84,41 +84,33 @@ pinned version of Rustc if you require compatibility with a specific version.
 
 ## Crate Features
 
-Rand is built with the `std` and `getrandom` features enabled by default:
-
--   `std` enables functionality dependent on the `std` lib and implies `alloc`
-    and `getrandom`
--   `getrandom` is an optional crate, providing the code behind `rngs::OsRng`;
-    the continued existance of this feature is not guaranteed so users are
-    encouraged to specify `std` instead
-
-The following optional features are available:
-
-- `alloc` can be used instead of `std` to provide `Vec` and `Box`.
-- `log` enables some logging via the `log` crate.
-- `nightly` enables all unstable features (`simd_support`).
-- `serde1` enables serialization for some types, via Serde version 1.
-- `simd_support` enables uniform sampling of SIMD types (integers and floats).
-- `stdweb` enables support for `OsRng` on `wasm32-unknown-unknown` via `stdweb`
-  combined with `cargo-web`.
-- `wasm-bindgen` enables support for `OsRng` on `wasm32-unknown-unknown` via
-  [`wasm-bindgen`]
-
-[`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen
-
-`no_std` mode is activated by setting `default-features = false`; this removes
-functionality depending on `std`:
-
-- `thread_rng()`, and `random()` are not available, as they require thread-local
-  storage and an entropy source.
-- Since no external entropy is available, it is not possible to create
-  generators with fresh seeds using the `FromEntropy` trait (user must provide
-  a seed).
-- Several non-linear distributions distributions are unavailable since `exp`
-  and `log` functions are not provided in `core`.
-- Large parts of the `seq`-uence module are unavailable, unless the `alloc`
-  feature is used (several APIs and many implementations require `Vec`).
+Rand is built with these features enabled by default:
 
+-   `std` enables functionality dependent on the `std` lib
+-   `alloc` (implied by `std`) enables functionality requiring an allocator
+-   `getrandom` (implied by `std`) is an optional dependency providing the code
+    behind `rngs::OsRng`
+
+Optionally, the following dependencies can be enabled:
+
+-   `log` enables logging via the `log` crate
+-   `serde1` enables serialization for some types, via Serde version 1
+-   `stdweb` implies `getrandom/stdweb` to enable
+    `getrandom` support on `wasm32-unknown-unknown`
+-   `wasm-bindgen` implies `getrandom/wasm-bindgen` to enable
+    `getrandom` support on `wasm32-unknown-unknown`
+
+Additionally, these features configure Rand:
+
+-   `nightly` enables all experimental features
+-   `simd_support` (experimental) enables sampling of SIMD values
+    (uniformly random SIMD integers and floats)
+
+Rand supports limited functionality in `no_std` mode (enabled via
+`default-features = false`). In this case, `OsRng` and `from_entropy` are
+unavailable (unless `getrandom` is enabled), large parts of `seq` are
+unavailable (unless `alloc` is enabled), and `thread_rng` and `random` are
+unavailable.
 
 # License