Merge pull request #200 from rust-random/doc_feature

Use doc_cfg to improve register_custom_getrandom docs

Author: josephlr

.github/workflows/tests.yml

@@ -21,7 +21,7 @@ jobs:
       - uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: nightly # Needed for -Z minimal-versions
+          toolchain: nightly # Needed for -Z minimal-versions and doc_cfg
           override: true
       - uses: Swatinem/rust-cache@v1
       - name: Install precompiled cargo-deadlinks
@@ -30,7 +30,10 @@ jobs:
           wget -O /tmp/cargo-deadlinks $URL
           chmod +x /tmp/cargo-deadlinks
           mv /tmp/cargo-deadlinks ~/.cargo/bin
-      - run: cargo deadlinks -- --features=custom,std
+      - name: Generate Docs
+        env:
+          RUSTDOCFLAGS: --cfg docsrs
+        run: cargo deadlinks -- --features=custom,std
       - run: |
           cargo generate-lockfile -Z minimal-versions
           cargo test --features=custom,std

Cargo.toml

@@ -50,3 +50,4 @@ test-in-browser = []
 
 [package.metadata.docs.rs]
 features = ["std", "custom"]
+rustdoc-args = ["--cfg", "docsrs"]

src/custom.rs

@@ -12,8 +12,6 @@ use core::num::NonZeroU32;
 
 /// Register a function to be invoked by `getrandom` on unsupported targets.
 ///
-/// *This API requires the `"custom"` Cargo feature to be activated*.
-///
 /// ## Writing a custom `getrandom` implementation
 ///
 /// The function to register must have the same signature as
@@ -75,6 +73,7 @@ use core::num::NonZeroU32;
 /// [top-level documentation](index.html#custom-implementations) this
 /// registration only has an effect on unsupported targets.
 #[macro_export]
+#[cfg_attr(docsrs, doc(cfg(feature = "custom")))]
 macro_rules! register_custom_getrandom {
     ($path:path) => {
         // We use an extern "C" function to get the guarantees of a stable ABI.

src/error_impls.rs

@@ -5,6 +5,7 @@
 // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
+#![cfg_attr(docsrs, doc(cfg(feature = "std")))]
 extern crate std;
 
 use crate::Error;

src/lib.rs

@@ -146,6 +146,7 @@
 )]
 #![no_std]
 #![warn(rust_2018_idioms, unused_lifetimes, missing_docs)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 #[macro_use]
 extern crate cfg_if;