doc: enable necessary features when building docs (#812)

* doc: enable all features when building docs

Signed-off-by: MrCroxx <[email protected]>

* doc: fix rustdoc for docs.rs with features, add CI

Signed-off-by: MrCroxx <[email protected]>

* chore: make ffmt happy

Signed-off-by: MrCroxx <[email protected]>

* fix: pass rustdoc test for docs.rs

Signed-off-by: MrCroxx <[email protected]>

* fix: fix rustdoc test ci

Signed-off-by: MrCroxx <[email protected]>

* fix: do not build docs for deps

Signed-off-by: MrCroxx <[email protected]>

---------

Signed-off-by: MrCroxx <[email protected]>

.github/workflows/ci.yml

@@ -216,6 +216,52 @@ jobs:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
         with:
           verbose: true
+  rustdoc-test:
+    name: rust doc test
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly
+      - name: Cache Cargo home
+        uses: actions/cache@v4
+        id: cache
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.toml') }}-${{ env.CACHE_KEY_SUFFIX }}-rustdoc-test
+      - name: Install NASM for aws-lc-rs on Windows
+        if: runner.os == 'Windows'
+        uses: ilammy/setup-nasm@v1
+      - name: Install ninja-build tool for aws-lc-fips-sys on Windows
+        if: runner.os == 'Windows'
+        uses: seanmiddleditch/gha-setup-ninja@v5
+      - name: Run rustdoc test
+        run: |
+          cargo test --features "nightly,prometheus,prometheus-client,prometheus-client_0_22,opentelemetry,opentelemetry_0_26,opentelemetry_0_27" --doc
+      - name: Test docs build with docs.rs
+        env:
+          RUSTDOCFLAGS: --cfg docsrs -D warnings
+        run: |
+          cargo doc --features "nightly,prometheus,prometheus-client,prometheus-client_0_22,opentelemetry,opentelemetry_0_26,opentelemetry_0_27" --no-deps
+      - name: Upload docs.rs docs as artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: foyer-docs-${{ github.sha }}-${{ runner.os }}
+          path: target/doc
+          if-no-files-found: error
+          retention-days: 7
+
   deadlock:
     name: run with single worker thread and deadlock detection
     runs-on: ubuntu-latest

Makefile

@@ -27,6 +27,7 @@ check-all:
 test:
 	RUST_BACKTRACE=1 cargo nextest run --all --features "strict_assertions,sanity,prometheus,prometheus-client_0_22,opentelemetry_0_26,opentelemetry_0_27"
 	RUST_BACKTRACE=1 cargo test --doc
+	RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo +nightly doc --features "nightly,prometheus,prometheus-client,prometheus-client_0_22,opentelemetry,opentelemetry_0_26,opentelemetry_0_27" --no-deps
 
 test-ignored:
 	RUST_BACKTRACE=1 cargo nextest run --run-ignored ignored-only --no-capture --workspace --features "strict_assertions,sanity"

foyer-cli/Cargo.toml

@@ -21,9 +21,5 @@ thiserror = { workspace = true }
 
 [dev-dependencies]
 
-[[bin]]
-name = "foyer"
-path = "src/main.rs"
-
 [lints]
 workspace = true

foyer-memory/src/eviction/lru.rs

@@ -32,7 +32,7 @@ use crate::{
 pub struct LruConfig {
     /// The ratio of the high priority pool occupied.
     ///
-    /// [`Lru`] guarantees that the high priority weight are always as larger as
+    /// `Lru` guarantees that the high priority weight are always as larger as
     /// but no larger that the capacity * high priority pool ratio.
     ///
     /// # Panic

foyer-memory/src/eviction/mod.rs

@@ -81,10 +81,6 @@ where
 ///
 /// [`Eviction`] is needs to be implemented to support a new cache eviction algorithm.
 ///
-/// For performance considerations, most APIs pass parameters via [`NonNull`] pointers to implement intrusive data
-/// structures. It is not required to implement the cache eviction algorithm using the [`NonNull`] pointers. They can
-/// also be used as a token for the target entry.
-///
 /// # Safety
 ///
 /// The pointer can be dereferenced as a mutable reference ***iff*** the `self` reference is also mutable.

foyer-memory/src/raw.rs

@@ -804,7 +804,7 @@ where
     }
 }
 
-/// The state of [`Fetch`].
+/// The state of `fetch`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FetchState {
     /// Cache hit.

foyer-memory/src/record.rs

@@ -38,7 +38,7 @@ pub enum CacheHint {
     Normal,
     /// Suggest the priority of the entry is low.
     ///
-    /// Used by [`crate::eviction::lru::Lru`].
+    /// Used by LRU.
     Low,
 }
 

foyer-storage/src/device/bytes.rs

@@ -436,7 +436,7 @@ impl IoBytes {
     ///
     /// Otherwise, [`None`] is returned.
     ///
-    /// It is strongly recommended to use `into_io_buffer` instead if you don't want to keep the original [`IoByes`]
+    /// It is strongly recommended to use `into_io_buffer` instead if you don't want to keep the original [`IoBytes`]
     /// in the [`Err`] path. See `Arc::try_unwrap` and `Arc::into_inner` docs.
     ///
     /// Note: The [`IoBytes`] can be a slice of the underlying [`IoBuffer`].

foyer/Cargo.toml

@@ -12,6 +12,19 @@ license = { workspace = true }
 readme = { workspace = true }
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[package.metadata.docs.rs]
+features = [
+    "nightly",
+    # build docs for exporters
+    "prometheus",
+    "prometheus-client",
+    "prometheus-client_0_22",
+    "opentelemetry",
+    "opentelemetry_0_26",
+    "opentelemetry_0_27",
+]
+rustdoc-args = ["--cfg", "docsrs"]
+
 [dependencies]
 ahash = { workspace = true }
 anyhow = "1"

foyer/src/hybrid/builder.rs

@@ -269,7 +269,7 @@ where
     ///
     /// The admission picker is used to pick the entries that can be inserted into the disk cache store.
     ///
-    /// Default: [`AdmitAllPicker`].
+    /// Default: [`crate::AdmitAllPicker`].
     pub fn with_admission_picker(self, admission_picker: Arc<dyn AdmissionPicker<Key = K>>) -> Self {
         let builder = self.builder.with_admission_picker(admission_picker);
         Self {

foyer/src/lib.rs

@@ -13,6 +13,7 @@
 //  limitations under the License.
 
 #![cfg_attr(feature = "nightly", feature(allocator_api))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 //! A hybrid cache library that supports plug-and-play cache algorithms, in-memory cache and disk cache.
 //!

foyer/src/prelude.rs

@@ -13,16 +13,22 @@
 //  limitations under the License.
 
 #[cfg(feature = "opentelemetry")]
+#[cfg_attr(docsrs, doc(cfg(feature = "opentelemetry")))]
 pub use crate::common::metrics::registry::opentelemetry;
 #[cfg(feature = "opentelemetry_0_26")]
+#[cfg_attr(docsrs, doc(cfg(feature = "opentelemetry_0_26")))]
 pub use crate::common::metrics::registry::opentelemetry_0_26;
 #[cfg(feature = "opentelemetry_0_27")]
+#[cfg_attr(docsrs, doc(cfg(feature = "opentelemetry_0_27")))]
 pub use crate::common::metrics::registry::opentelemetry_0_27;
 #[cfg(feature = "prometheus")]
+#[cfg_attr(docsrs, doc(cfg(feature = "prometheus")))]
 pub use crate::common::metrics::registry::prometheus;
 #[cfg(feature = "prometheus-client")]
+#[cfg_attr(docsrs, doc(cfg(feature = "prometheus-client")))]
 pub use crate::common::metrics::registry::prometheus_client;
 #[cfg(feature = "prometheus-client_0_22")]
+#[cfg_attr(docsrs, doc(cfg(feature = "prometheus-client_0_22")))]
 pub use crate::common::metrics::registry::prometheus_client_0_22;
 pub use crate::{
     common::{