getrandom-js: Document the custom RNG crate

The documentation can be previewed by running:
  cargo doc --no-deps --open --package getrandom-js --target=wasm32-unknown-unknown

Signed-off-by: Joe Richey <[email protected]>

Author: josephlr

custom/js/src/lib.rs

@@ -1,3 +1,43 @@
+//! External getrandom implementation for use with JavaScript
+//!
+//! The crate uses [`getrandom`'s custom implementation mechanism][1] to provide
+//! support for JavaScript environments on the `wasm32-unknown-unknown` target.
+//!
+//! This crate supports web browsers and Node.js by directly calling the
+//! appropriate JavaScript functions. Specifically:
+//!   - On web browsers, [`Crypto.getRandomValues`][2] is used.
+//!   - On Node.js [`crypto.randomBytes`][3] is used.
+//!
+//! This crate works with either the [`wasm-bindgen`][4] or [`stdweb`][5]
+//! JavaScript shims. The correct shim will be automatically selected at compile
+//! time. Note that using `stdweb` requires [`cargo web`][6] v0.6.24 or higher.
+//!
+//! ## Using this crate
+//!
+//! First, depend on this crate by adding the following to your crate's `Cargo.toml`:
+//! ```toml
+//! [target.wasm32-unknown-unknown.dependencies]
+//! getrandom-js = 0.1
+//! ```
+//! Next, use `getrandom-js` somewhere in your crate. Explicit usage is
+//! needed to avoid linker errors. This can be done by adding the following to
+//! your crate's `src/lib.rs` or `src/main.rs`.
+//! ```rust
+//! #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
+//! use getrandom_js as _;
+//! ```
+//!
+//! Now, any use of `getrandom` (either as a direct or indirect dependency of
+//! your crate) on the `wasm32-unknown-unknown` target will call into the
+//! implementation defined by this crate.
+//!
+//! [1]: https://docs.rs/getrandom/#use-a-custom-implementation
+//! [2]: https://www.w3.org/TR/WebCryptoAPI/#Crypto-method-getRandomValues
+//! [3]: https://nodejs.org/api/crypto.html#crypto_crypto_randombytes_size_callback
+//! [4]: https://github.com/rustwasm/wasm-bindgen
+//! [5]: https://github.com/koute/stdweb
+//! [6]: https://github.com/koute/cargo-web
+
 // Necessary to work around complex macros in stdweb
 #![cfg_attr(cargo_web, recursion_limit = "128")]