From 95e8c78db8fef4fcc12a9cbf0a52753049070e4b Mon Sep 17 00:00:00 2001 From: Dave Tucker Date: Tue, 4 Oct 2022 13:24:13 +0000 Subject: [PATCH] docs: Add labels for optional features Following the lead of crates like tokio and nix, we now annotate APIs that require optional features. This helps in cases where a user wants to have an `AsyncPerfEventArray` which is documented on crates.io, but it's not obvious that you have to enable the `async` feature. Signed-off-by: Dave Tucker --- aya/Cargo.toml | 4 ++++ aya/src/lib.rs | 1 + aya/src/maps/perf/async_perf_event_array.rs | 2 +- aya/src/maps/perf/mod.rs | 6 ++++-- aya/src/programs/links.rs | 2 +- xtask/src/docs/mod.rs | 5 ++++- 6 files changed, 15 insertions(+), 5 deletions(-) diff --git a/aya/Cargo.toml b/aya/Cargo.toml index 3442c76c..edf6445e 100644 --- a/aya/Cargo.toml +++ b/aya/Cargo.toml @@ -32,3 +32,7 @@ default = [] async = ["futures"] async_tokio = ["tokio", "async"] async_std = ["async-std", "async-io", "async"] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] \ No newline at end of file diff --git a/aya/src/lib.rs b/aya/src/lib.rs index 6666f20d..14f3eb2d 100644 --- a/aya/src/lib.rs +++ b/aya/src/lib.rs @@ -36,6 +36,7 @@ html_logo_url = "https://aya-rs.dev/assets/images/crabby.svg", html_favicon_url = "https://aya-rs.dev/assets/images/crabby.svg" )] +#![cfg_attr(docsrs, feature(doc_cfg))] #![deny(clippy::all, missing_docs)] #![allow(clippy::missing_safety_doc, clippy::len_without_is_empty)] diff --git a/aya/src/maps/perf/async_perf_event_array.rs b/aya/src/maps/perf/async_perf_event_array.rs index 332a21d1..1c14fc6a 100644 --- a/aya/src/maps/perf/async_perf_event_array.rs +++ b/aya/src/maps/perf/async_perf_event_array.rs @@ -137,7 +137,7 @@ pub struct AsyncPerfEventArrayBuffer> { async_fd: Async, } -#[cfg(any(feature = "async_tokio", doc))] +#[cfg(any(feature = "async_tokio"))] impl> AsyncPerfEventArrayBuffer { /// Reads events from the buffer. /// diff --git a/aya/src/maps/perf/mod.rs b/aya/src/maps/perf/mod.rs index f4770275..1f9bae7d 100644 --- a/aya/src/maps/perf/mod.rs +++ b/aya/src/maps/perf/mod.rs @@ -1,12 +1,14 @@ //! Ring buffer types used to receive events from eBPF programs using the linux `perf` API. //! //! See the [`PerfEventArray`] and [`AsyncPerfEventArray`]. -#[cfg(any(feature = "async", doc))] +#[cfg(any(feature = "async"))] +#[cfg_attr(docsrs, doc(cfg(feature = "async")))] mod async_perf_event_array; mod perf_buffer; mod perf_event_array; -#[cfg(any(feature = "async", doc))] +#[cfg(any(feature = "async"))] +#[cfg_attr(docsrs, doc(cfg(feature = "async")))] pub use async_perf_event_array::*; pub use perf_buffer::*; pub use perf_event_array::*; diff --git a/aya/src/programs/links.rs b/aya/src/programs/links.rs index 5efee10f..58d0ed12 100644 --- a/aya/src/programs/links.rs +++ b/aya/src/programs/links.rs @@ -95,7 +95,7 @@ impl FdLink { /// Pins the link to a BPF file system. /// /// When a link is pinned it will remain attached even after the link instance is dropped, - /// and will only be detached once the pinned file is removed. To unpin, see [PinnedFd::unpin]. + /// and will only be detached once the pinned file is removed. To unpin, see [`PinnedLink::unpin()`]. /// /// The parent directories in the provided path must already exist before calling this method, /// and must be on a BPF file system (bpffs). diff --git a/xtask/src/docs/mod.rs b/xtask/src/docs/mod.rs index dfdd827f..669852c6 100644 --- a/xtask/src/docs/mod.rs +++ b/xtask/src/docs/mod.rs @@ -67,7 +67,10 @@ fn build_docs(working_dir: &PathBuf, abs_header_path: &Path) -> Result<(), anyho .current_dir(working_dir) .env( "RUSTDOCFLAGS", - format!("--html-in-header {}", abs_header_path.to_str().unwrap()), + format!( + "--cfg docsrs --html-in-header {}", + abs_header_path.to_str().unwrap() + ), ) .args(&args) .status()