From 82edd681c398f73de026a695837dd37643ed124a Mon Sep 17 00:00:00 2001 From: Andrew Stoycos Date: Thu, 20 Oct 2022 14:46:40 -0400 Subject: [PATCH] Fix doc links, update rustdoc args Fix some broken rust doc links. Make sure rustdoc build fail on warnings so we catch these broken links in CI. Signed-off-by: Andrew Stoycos --- aya/Cargo.toml | 2 +- aya/src/bpf.rs | 9 ++++----- aya/src/maps/mod.rs | 18 +++++++++--------- aya/src/maps/perf/mod.rs | 2 +- aya/src/maps/sock/mod.rs | 2 +- aya/src/maps/sock/sock_hash.rs | 2 +- aya/src/maps/sock/sock_map.rs | 2 +- xtask/src/docs/mod.rs | 2 +- 8 files changed, 19 insertions(+), 20 deletions(-) diff --git a/aya/Cargo.toml b/aya/Cargo.toml index 8c43a401..c5b2f01d 100644 --- a/aya/Cargo.toml +++ b/aya/Cargo.toml @@ -34,4 +34,4 @@ async_std = ["async-io", "async"] [package.metadata.docs.rs] all-features = true -rustdoc-args = ["--cfg", "docsrs"] +rustdoc-args = ["--cfg", "docsrs","-D", "warnings"] diff --git a/aya/src/bpf.rs b/aya/src/bpf.rs index bd8dd1a3..f5307f83 100644 --- a/aya/src/bpf.rs +++ b/aya/src/bpf.rs @@ -760,11 +760,10 @@ impl Bpf { /// Takes ownership of a map with the given name. /// - /// This API is intended for cases where the map must be moved into spawned - /// task. For example, when using an [`AsyncPerfEventArray`]. For map interactions - /// without taking ownership, see `map` or `map_mut`. An owned map will be - /// closed on `Drop`, therefore the the caller is now responsible for managing - /// its lifetime. + /// Use this when borrowing with [`map`](crate::Bpf::map) or [`map_mut`](crate::Bpf::map_mut) + /// is not possible (eg when using the map from an async task). The returned + /// map will be closed on `Drop`, therefore the caller is responsible for + /// managing its lifetime. /// /// The returned type is mostly opaque. In order to do anything useful with it you need to /// convert it to a [typed map](crate::maps). diff --git a/aya/src/maps/mod.rs b/aya/src/maps/mod.rs index 8930128d..e0b980be 100644 --- a/aya/src/maps/mod.rs +++ b/aya/src/maps/mod.rs @@ -5,16 +5,16 @@ //! [`Bpf::load_file`](crate::Bpf::load_file) or //! [`Bpf::load`](crate::Bpf::load), all the maps defined in the eBPF code get //! initialized and can then be accessed using [`Bpf::map`](crate::Bpf::map), -//! [`Bpf::map_mut`](crate::Bpf::map_mut), [`Bpf::take_map`](crate::Bpf::map) -//! or [`Bpf::map_mut`](crate::Bpf::take_map). +//! [`Bpf::map_mut`](crate::Bpf::map_mut), or [`Bpf::take_map`](crate::Bpf::take_map). //! //! # Typed maps //! //! The eBPF API includes many map types each supporting different operations. //! [`Bpf::map`](crate::Bpf::map), [`Bpf::map_mut`](crate::Bpf::map_mut), and -//! [`Bpf::map_mut`](crate::Bpf::take_map) always return the -//! opaque [`&Map`], [`&mut Map`], and [`Map`] types respectively. Those three types can be converted to -//! *typed maps* using the [`TryFrom`](std::convert::TryFrom) or [`TryInto`](std::convert::TryInto) +//! [`Bpf::take_map`](crate::Bpf::take_map) always return the +//! opaque [`&Map`](crate::maps::Map), [`&mut Map`](crate::maps::Map), and [`Map`](crate::maps::Map) +//! types respectively. Those three types can be converted to *typed maps* using +//! the [`TryFrom`](std::convert::TryFrom) or [`TryInto`](std::convert::TryInto) //! trait. For example: //! //! ```no_run @@ -233,7 +233,7 @@ fn maybe_warn_rlimit() { /// eBPF map types. #[derive(Debug)] pub enum Map { - /// A ['Array`] map + /// A [`Array`] map Array(MapData), /// A [`PerCpuArray`] map PerCpuArray(MapData), @@ -241,7 +241,7 @@ pub enum Map { ProgramArray(MapData), /// A [`HashMap`] map HashMap(MapData), - /// A ['PerCpuHashMap'] map + /// A [`PerCpuHashMap`] map PerCpuHashMap(MapData), /// A [`PerfEventArray`] map PerfEventArray(MapData), @@ -255,7 +255,7 @@ pub enum Map { LpmTrie(MapData), /// A [`Stack`] map Stack(MapData), - /// A [`StackTrace`] map + /// A [`StackTraceMap`] map StackTraceMap(MapData), /// A [`Queue`] map Queue(MapData), @@ -556,7 +556,7 @@ impl MapData { /// Loads a map from a [`RawFd`]. /// - /// If loading from a BPF Filesystem (bpffs) you should use [`Map::from_pin`]. + /// If loading from a BPF Filesystem (bpffs) you should use [`Map::from_pin`](crate::maps::MapData::from_pin). /// This API is intended for cases where you have received a valid BPF FD from some other means. /// For example, you received an FD over Unix Domain Socket. pub fn from_fd(fd: RawFd) -> Result { diff --git a/aya/src/maps/perf/mod.rs b/aya/src/maps/perf/mod.rs index 1f9bae7d..db3c3005 100644 --- a/aya/src/maps/perf/mod.rs +++ b/aya/src/maps/perf/mod.rs @@ -1,6 +1,6 @@ //! Ring buffer types used to receive events from eBPF programs using the linux `perf` API. //! -//! See the [`PerfEventArray`] and [`AsyncPerfEventArray`]. +//! See the [`PerfEventArray`](crate::maps::PerfEventArray) and [`AsyncPerfEventArray`](crate::maps::perf::AsyncPerfEventArray). #[cfg(any(feature = "async"))] #[cfg_attr(docsrs, doc(cfg(feature = "async")))] mod async_perf_event_array; diff --git a/aya/src/maps/sock/mod.rs b/aya/src/maps/sock/mod.rs index 59979896..ffbf7aa3 100644 --- a/aya/src/maps/sock/mod.rs +++ b/aya/src/maps/sock/mod.rs @@ -7,7 +7,7 @@ pub use sock_map::SockMap; use std::os::unix::io::{AsRawFd, RawFd}; -/// A [`SocketMap`] file descriptor. +/// A socket map file descriptor. #[derive(Copy, Clone)] pub struct SockMapFd(RawFd); diff --git a/aya/src/maps/sock/sock_hash.rs b/aya/src/maps/sock/sock_hash.rs index 679c2be3..4271f5e6 100644 --- a/aya/src/maps/sock/sock_hash.rs +++ b/aya/src/maps/sock/sock_hash.rs @@ -107,7 +107,7 @@ impl, K: Pod> SockHash { /// Returns the map's file descriptor. /// /// The returned file descriptor can be used to attach programs that work with - /// socket maps, like [`SkMsg`] and [`SkSkb`]. + /// socket maps, like [`SkMsg`](crate::programs::SkMsg) and [`SkSkb`](crate::programs::SkSkb). pub fn fd(&self) -> Result { Ok(SockMapFd(self.inner.as_ref().fd_or_err()?)) } diff --git a/aya/src/maps/sock/sock_map.rs b/aya/src/maps/sock/sock_map.rs index 7c284d22..28c5b404 100644 --- a/aya/src/maps/sock/sock_map.rs +++ b/aya/src/maps/sock/sock_map.rs @@ -63,7 +63,7 @@ impl> SockMap { /// Returns the map's file descriptor. /// /// The returned file descriptor can be used to attach programs that work with - /// socket maps, like [`SkMsg`] and [`SkSkb`]. + /// socket maps, like [`SkMsg`](crate::programs::SkMsg) and [`SkSkb`](crate::programs::SkSkb). pub fn fd(&self) -> Result { Ok(SockMapFd(self.inner.as_ref().fd_or_err()?)) } diff --git a/xtask/src/docs/mod.rs b/xtask/src/docs/mod.rs index 669852c6..b6779cba 100644 --- a/xtask/src/docs/mod.rs +++ b/xtask/src/docs/mod.rs @@ -68,7 +68,7 @@ fn build_docs(working_dir: &PathBuf, abs_header_path: &Path) -> Result<(), anyho .env( "RUSTDOCFLAGS", format!( - "--cfg docsrs --html-in-header {}", + "--cfg docsrs --html-in-header {} -D warnings", abs_header_path.to_str().unwrap() ), )