From 8e329abfe1745ac3e4c068520cd3551218d0e4a8 Mon Sep 17 00:00:00 2001 From: MrCroxx Date: Tue, 3 Dec 2024 12:30:20 +0800 Subject: [PATCH 1/6] doc: enable all features when building docs Signed-off-by: MrCroxx --- foyer-bench/Cargo.toml | 3 +++ foyer-common/Cargo.toml | 3 +++ foyer-memory/Cargo.toml | 3 +++ foyer-storage/Cargo.toml | 3 +++ foyer/Cargo.toml | 3 +++ 5 files changed, 15 insertions(+) diff --git a/foyer-bench/Cargo.toml b/foyer-bench/Cargo.toml index b629d8b9..44cb3882 100644 --- a/foyer-bench/Cargo.toml +++ b/foyer-bench/Cargo.toml @@ -12,6 +12,9 @@ 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] +all-features = true + [dependencies] anyhow = "1" bytesize = { workspace = true } diff --git a/foyer-common/Cargo.toml b/foyer-common/Cargo.toml index 33e09ea9..544eafab 100644 --- a/foyer-common/Cargo.toml +++ b/foyer-common/Cargo.toml @@ -12,6 +12,9 @@ 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] +all-features = true + [dependencies] ahash = { workspace = true } bytes = "1" diff --git a/foyer-memory/Cargo.toml b/foyer-memory/Cargo.toml index 35d3e6ff..13df8408 100644 --- a/foyer-memory/Cargo.toml +++ b/foyer-memory/Cargo.toml @@ -12,6 +12,9 @@ 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] +all-features = true + [dependencies] ahash = { workspace = true } bitflags = "2" diff --git a/foyer-storage/Cargo.toml b/foyer-storage/Cargo.toml index c1955f2d..23451549 100644 --- a/foyer-storage/Cargo.toml +++ b/foyer-storage/Cargo.toml @@ -12,6 +12,9 @@ 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] +all-features = true + [dependencies] ahash = { workspace = true } # TODO(MrCroxx): Remove this after `allocator_api` is stable. diff --git a/foyer/Cargo.toml b/foyer/Cargo.toml index 2b7c4db9..581706f5 100644 --- a/foyer/Cargo.toml +++ b/foyer/Cargo.toml @@ -12,6 +12,9 @@ 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] +all-features = true + [dependencies] ahash = { workspace = true } anyhow = "1" From 2eb507c0912ceee088e87fc9049fa2173f081542 Mon Sep 17 00:00:00 2001 From: MrCroxx Date: Tue, 3 Dec 2024 14:41:12 +0800 Subject: [PATCH 2/6] doc: fix rustdoc for docs.rs with features, add CI Signed-off-by: MrCroxx --- .github/workflows/ci.yml | 46 ++++++++++++++++++++++++++++++++ foyer-bench/Cargo.toml | 3 --- foyer-cli/Cargo.toml | 4 --- foyer-common/Cargo.toml | 3 --- foyer-memory/Cargo.toml | 3 --- foyer-memory/src/eviction/lru.rs | 2 +- foyer-memory/src/eviction/mod.rs | 4 --- foyer-storage/Cargo.toml | 3 --- foyer/Cargo.toml | 12 ++++++++- foyer/src/lib.rs | 1 + foyer/src/prelude.rs | 12 +++++++++ 11 files changed, 71 insertions(+), 22 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1f3466a5..9697560a 100644 --- a/.github/workflows/ci.yml +++ b/.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" + - name: Upload docs.rs docs as artifacts + uses: actions/upload-artifact@v4 + with: + name: docs + 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 diff --git a/foyer-bench/Cargo.toml b/foyer-bench/Cargo.toml index 44cb3882..b629d8b9 100644 --- a/foyer-bench/Cargo.toml +++ b/foyer-bench/Cargo.toml @@ -12,9 +12,6 @@ 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] -all-features = true - [dependencies] anyhow = "1" bytesize = { workspace = true } diff --git a/foyer-cli/Cargo.toml b/foyer-cli/Cargo.toml index c07556b9..7d36f271 100644 --- a/foyer-cli/Cargo.toml +++ b/foyer-cli/Cargo.toml @@ -21,9 +21,5 @@ thiserror = { workspace = true } [dev-dependencies] -[[bin]] -name = "foyer" -path = "src/main.rs" - [lints] workspace = true diff --git a/foyer-common/Cargo.toml b/foyer-common/Cargo.toml index 544eafab..33e09ea9 100644 --- a/foyer-common/Cargo.toml +++ b/foyer-common/Cargo.toml @@ -12,9 +12,6 @@ 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] -all-features = true - [dependencies] ahash = { workspace = true } bytes = "1" diff --git a/foyer-memory/Cargo.toml b/foyer-memory/Cargo.toml index 13df8408..35d3e6ff 100644 --- a/foyer-memory/Cargo.toml +++ b/foyer-memory/Cargo.toml @@ -12,9 +12,6 @@ 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] -all-features = true - [dependencies] ahash = { workspace = true } bitflags = "2" diff --git a/foyer-memory/src/eviction/lru.rs b/foyer-memory/src/eviction/lru.rs index 63038e5e..c49fa206 100644 --- a/foyer-memory/src/eviction/lru.rs +++ b/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 diff --git a/foyer-memory/src/eviction/mod.rs b/foyer-memory/src/eviction/mod.rs index f3401fb5..66ac4346 100644 --- a/foyer-memory/src/eviction/mod.rs +++ b/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. diff --git a/foyer-storage/Cargo.toml b/foyer-storage/Cargo.toml index 23451549..c1955f2d 100644 --- a/foyer-storage/Cargo.toml +++ b/foyer-storage/Cargo.toml @@ -12,9 +12,6 @@ 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] -all-features = true - [dependencies] ahash = { workspace = true } # TODO(MrCroxx): Remove this after `allocator_api` is stable. diff --git a/foyer/Cargo.toml b/foyer/Cargo.toml index 581706f5..9a90060f 100644 --- a/foyer/Cargo.toml +++ b/foyer/Cargo.toml @@ -13,7 +13,17 @@ readme = { workspace = true } # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [package.metadata.docs.rs] -all-features = true +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 } diff --git a/foyer/src/lib.rs b/foyer/src/lib.rs index ecc1a3d4..11b06c36 100644 --- a/foyer/src/lib.rs +++ b/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. //! diff --git a/foyer/src/prelude.rs b/foyer/src/prelude.rs index 2873547b..6c86ed75 100644 --- a/foyer/src/prelude.rs +++ b/foyer/src/prelude.rs @@ -13,17 +13,29 @@ // 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::{ buf::{BufExt, BufMutExt}, From 0ef292b70c719f6908148c8ee38780ab5f8af7e1 Mon Sep 17 00:00:00 2001 From: MrCroxx Date: Tue, 3 Dec 2024 14:45:22 +0800 Subject: [PATCH 3/6] chore: make ffmt happy Signed-off-by: MrCroxx --- foyer/src/prelude.rs | 6 ------ 1 file changed, 6 deletions(-) diff --git a/foyer/src/prelude.rs b/foyer/src/prelude.rs index 6c86ed75..f08520b0 100644 --- a/foyer/src/prelude.rs +++ b/foyer/src/prelude.rs @@ -15,27 +15,21 @@ #[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::{ buf::{BufExt, BufMutExt}, From 4a3cfca7b95c16bb4c4c470f95457fc59e51bd72 Mon Sep 17 00:00:00 2001 From: MrCroxx Date: Tue, 3 Dec 2024 14:52:06 +0800 Subject: [PATCH 4/6] fix: pass rustdoc test for docs.rs Signed-off-by: MrCroxx --- Makefile | 1 + foyer-memory/src/raw.rs | 2 +- foyer-memory/src/record.rs | 2 +- foyer-storage/src/device/bytes.rs | 2 +- foyer/src/hybrid/builder.rs | 2 +- 5 files changed, 5 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index c2a2777b..4c8346ea 100644 --- a/Makefile +++ b/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" test-ignored: RUST_BACKTRACE=1 cargo nextest run --run-ignored ignored-only --no-capture --workspace --features "strict_assertions,sanity" diff --git a/foyer-memory/src/raw.rs b/foyer-memory/src/raw.rs index ed2a0ff1..76a9b64b 100644 --- a/foyer-memory/src/raw.rs +++ b/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. diff --git a/foyer-memory/src/record.rs b/foyer-memory/src/record.rs index cecfc831..ef30c45c 100644 --- a/foyer-memory/src/record.rs +++ b/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, } diff --git a/foyer-storage/src/device/bytes.rs b/foyer-storage/src/device/bytes.rs index d7dece75..6bc6c43b 100644 --- a/foyer-storage/src/device/bytes.rs +++ b/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`]. diff --git a/foyer/src/hybrid/builder.rs b/foyer/src/hybrid/builder.rs index 45252d87..0f53e7de 100644 --- a/foyer/src/hybrid/builder.rs +++ b/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>) -> Self { let builder = self.builder.with_admission_picker(admission_picker); Self { From 6909130dc48819eb1c4e68862c313ca0d53bb0c1 Mon Sep 17 00:00:00 2001 From: MrCroxx Date: Tue, 3 Dec 2024 15:14:13 +0800 Subject: [PATCH 5/6] fix: fix rustdoc test ci Signed-off-by: MrCroxx --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9697560a..bee62464 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -257,7 +257,7 @@ jobs: - name: Upload docs.rs docs as artifacts uses: actions/upload-artifact@v4 with: - name: docs + name: foyer-docs-${{ github.sha }}-${{ runner.os }} path: target/doc if-no-files-found: error retention-days: 7 From 7a96e7a682357efd851b524ef443695a5a8f4e90 Mon Sep 17 00:00:00 2001 From: MrCroxx Date: Tue, 3 Dec 2024 15:22:24 +0800 Subject: [PATCH 6/6] fix: do not build docs for deps Signed-off-by: MrCroxx --- .github/workflows/ci.yml | 2 +- Makefile | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bee62464..0bf69f12 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -253,7 +253,7 @@ jobs: 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" + 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: diff --git a/Makefile b/Makefile index 4c8346ea..da0606f4 100644 --- a/Makefile +++ b/Makefile @@ -27,7 +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" + 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"