Show features (futures) in docs (#151)

The fact that there is a `futures` feature flag and a `block_on` method
was a bit hard to discover. At least for me. That lead me to create
#148. Turns out it was not needed.

To make it more discoverable, this PR makes docs.rs build the
documentation with all features active, so the extra functionality they
enable are visible. It also uses the unstable `doc_cfg` attribute to
make it more obvious in the docs that those items are feature gated.

This is taken more or less directly from how the tokio crate does the
same thing.

Co-authored-by: Eliza Weisman <eliza@buoyant.io>

.github/workflows/ci.yml

@@ -57,3 +57,16 @@ jobs:
         run: cargo check --features checkpoint
       - name: Test --features futures
         run: cargo test --features futures
+
+  # check docs
+  docs:
+    name: build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Rust
+        run: rustup update nightly && rustup default nightly
+      - name: cargo doc
+        run: cargo doc --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: "--cfg docsrs -Dwarnings"

Cargo.toml

@@ -40,3 +40,7 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 
 [dev-dependencies]
 futures-util = "0.3.0"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

ci/azure-check-docs.yml

@@ -0,0 +1,15 @@
+jobs:
+# Check docs
+- job: ${{ parameters.name }}
+  displayName: Check docs
+  pool:
+    vmImage: ubuntu-16.04
+  steps:
+    - template: azure-install-rust.yml
+      parameters:
+        rust_version: ${{ parameters.rust }}
+
+    - script: |
+        RUSTDOCFLAGS="--cfg docsrs" cargo doc --lib --no-deps --all-features
+      displayName: Check docs
+

src/lib.rs

@@ -1,4 +1,5 @@
 #![deny(missing_debug_implementations, missing_docs, rust_2018_idioms)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 //! Loom is a tool for testing concurrent programs.
 //!
@@ -349,6 +350,7 @@ macro_rules! if_futures {
     ($($t:tt)*) => {
         cfg_if::cfg_if! {
             if #[cfg(feature = "futures")] {
+                #[cfg_attr(docsrs, doc(cfg(feature = "futures")))]
                 $($t)*
             }
         }