Add description about Cargo js feature for WebAssembly section (#280)

* add description about Cargo js feature
* add note about different crate types
* clean up
* Fix wording/grammer
* Remove "Indirect Depenencies" section
* Note that libraries shouldn't add their own JS feature

Signed-off-by: Joe Richey <[email protected]>
Co-authored-by: Mauri Mustonen <[email protected]>
Co-authored-by: Joe Richey <[email protected]>

Author: 3 people

src/lib.rs

@@ -74,6 +74,21 @@
 //! and Node.js environments are supported, invoking the methods
 //! [described above](#supported-targets) using the [`wasm-bindgen`] toolchain.
 //!
+//! To enable the `js` Cargo feature, add the following to the `dependencies`
+//! section in your `Cargo.toml` file:
+//! ```toml
+//! [dependencies]
+//! getrandom = { version = "0.2", features = ["js"] }
+//! ```
+//!
+//! This can be done even if `getrandom` is not a direct dependency. Cargo
+//! allows crates to enable features for indirect dependencies.
+//!
+//! This feature should only be enabled for binary, test, or benchmark crates.
+//! Library crates should generally not enable this feature, leaving such a
+//! decision to *users* of their library. Also, libraries should not introduce
+//! their own `js` features *just* to enable `getrandom`'s `js` feature.
+//!
 //! This feature has no effect on targets other than `wasm32-unknown-unknown`.
 //!
 //! ### Custom implementations
@@ -88,16 +103,6 @@
 //! using `rdrand` and `js` Cargo features) continue using their normal
 //! implementations even if a function is registered.
 //!
-//! ### Indirect Dependencies
-//!
-//! If `getrandom` is not a direct dependency of your crate, you can still
-//! enable any of the above fallback behaviors by enabling the relevant
-//! feature in your root crate's `Cargo.toml`:
-//! ```toml
-//! [dependencies]
-//! getrandom = { version = "0.2", features = ["js"] }
-//! ```
-//!
 //! ## Early boot
 //!
 //! Sometimes, early in the boot process, the OS has not collected enough