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 <[email protected]>

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"]

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)]
 

aya/src/maps/perf/async_perf_event_array.rs

@@ -137,7 +137,7 @@ pub struct AsyncPerfEventArrayBuffer<T: DerefMut<Target = Map>> {
     async_fd: Async<RawFd>,
 }
 
-#[cfg(any(feature = "async_tokio", doc))]
+#[cfg(any(feature = "async_tokio"))]
 impl<T: DerefMut<Target = Map>> AsyncPerfEventArrayBuffer<T> {
     /// Reads events from the buffer.
     ///

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::*;

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).

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()