docs: Clarify when/where to use custom implementations

Signed-off-by: Joe Richey <joerichey@google.com>

src/custom.rs

@@ -25,12 +25,12 @@ use core::num::NonZeroU32;
 /// [dependencies]
 /// getrandom = { version = "0.2", features = ["custom"] }
 /// ```
-/// 
+///
 /// Next, in `dummy-getrandom/src/lib.rs`, we define our custom implementation and register it:
 /// ```rust
 /// use core::num::NonZeroU32;
 /// use getrandom::{Error, register_custom_getrandom};
-/// 
+///
 /// const MY_CUSTOM_ERROR_CODE: u32 = Error::CUSTOM_START + 42;
 /// fn always_fail(buf: &mut [u8]) -> Result<(), Error> {
 ///     let code = NonZeroU32::new(MY_CUSTOM_ERROR_CODE).unwrap();
@@ -43,10 +43,9 @@ use core::num::NonZeroU32;
 /// [`getrandom::getrandom`](crate::getrandom).
 ///
 /// Now any user of `getrandom` (direct or indirect) on this target will use the
-/// above custom implementation. Note that if you are using a helper-crate, some
-/// crate in the build needs to depend on `dummy-getrandom` via a
-/// `use dummy_getrandom;` statement. Failure to do this will result
-/// in linker errors.
+/// above custom implementation. See the
+/// [usage documentation](index.html#use-a-custom-implementation) for information about
+/// _using_ such a custom implementation.
 #[macro_export]
 macro_rules! register_custom_getrandom {
     ($path:path) => {

src/lib.rs

@@ -82,6 +82,21 @@
 //! are building for an unsupported target, `getrandom` will use this external
 //! implementation instead of failing to compile.
 //!
+//! Using such an external implementation requires depending on it in your
+//! `Cargo.toml` _and_ using it in your binary crate with:
+//! ```ignore
+//! use some_custom_getrandom_crate;
+//! ```
+//! (failure to do this will cause linker errors).
+//!
+//! Other than [dev-dependencies](https://doc.rust-lang.org/stable/rust-by-example/testing/dev_dependencies.html),
+//! library crates should **not** depend on external implementation crates.
+//! Only binary crates should depend/use such crates. This is similar to
+//! [`#[panic_handler]`](https://doc.rust-lang.org/nomicon/panic-handler.html) or
+//! [`#[global_allocator]`](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/global-allocators.html),
+//! where helper crates define handlers/allocators but only the binary crate
+//! actually _uses_ the functionality.
+//!
 //! See [`register_custom_getrandom!`] for information about writing your own
 //! custom `getrandom` implementation for an unsupported target.
 //!